VOL1STLN1 THE STATUSLINE                                    DUB19850615
=======================================================================
         ____ _____  _  _____ _   _ ____  _     ___ _   _ _____
        / ___|_   _|/ \|_   _| | | / ___|| |   |_ _| \ | | ____|
        \___ \ | | / _ \ | | | | | \___ \| |    | ||  \| |  _|
         ___) || |/ ___ \| | | |_| |___) | |___ | || |\  | |___
        |____/ |_/_/   \_\_|  \___/|____/|_____|___|_| \_|_____|

=======================================================================

                         + TABLE OF CONTENTS +

1. PREFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
2. CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . .  2
   2.1. CFGLIB . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
   2.2. GENERAL STRUCTURE OF THE CONFIGURATION RECORD  . . . . . . .  2
   2.3. LIST OF SUPPORTED COMMANDS . . . . . . . . . . . . . . . . .  3
   2.4. LIST OF SUPPORTED MODULES  . . . . . . . . . . . . . . . . .  4
   2.5. LIST OF THEMES . . . . . . . . . . . . . . . . . . . . . . .  5
   2.6. LIST OF SUPPORTED COLORS . . . . . . . . . . . . . . . . . .  5
   2.7. ABEND CODES  . . . . . . . . . . . . . . . . . . . . . . . .  5
3. COMPILING THE PROJECT . . . . . . . . . . . . . . . . . . . . . .  5
   3.1. LIST OF SUPPORTED STANDARDS  . . . . . . . . . . . . . . . .  6
   3.2. COMPILING THE PROJECT  . . . . . . . . . . . . . . . . . . .  6
      3.2.1. COMPILING USING NIX . . . . . . . . . . . . . . . . . .  6
4. HACKING . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
   4.1. KNOWN ISSUES . . . . . . . . . . . . . . . . . . . . . . . .  7
      4.1.1. Y2K . . . . . . . . . . . . . . . . . . . . . . . . . .  7
   4.2. WRITING MODULES  . . . . . . . . . . . . . . . . . . . . . .  7
   4.3. TO DO LIST . . . . . . . . . . . . . . . . . . . . . . . . .  8

=======================================================================
==============================  PREFACE  ==============================

   SIMPLE STATUS LINE WRITTEN IN THE BEST PROGRAMMING LANGUAGE EVER.

/

=======================================================================
===========================  CONFIGURATION  ===========================

===== CFGLIB

STATUSLINE-COB LOOKS FOR THE CONFIGURATION DATA SET IN THE FOLLOWING
LOCATIONS:
- $STATUSLINE_CONFIG                   (IF SET)
- ./STATUSLINE-COB.CFG
- $XDG_CONFIG_HOME/STATUSLINE-COB/CONFIG.CFG
- $HOME/.config/STATUSLINE-COB/CONFIG.CFG
- $HOME/.STATUSLINE-COB.CFG
- /etc/STATUSLINE/STATUSLINE.CFG
- /etc/STATUSLINE-COB.CFG
- $STATUSLINE_CONFIG_END               (IF SET)
IF THE CONFIGURATION IS NOT FOUND IN ANY CFGLIB, THE STATUSLINE LOADS THE
DEFAULT CONFIGURATION (SEE 2.2).

===== GENERAL STRUCTURE OF THE CONFIGURATION RECORD

CFGLIB IS A LINE SEQUENTIAL DATA SET WITH RECORDS HAVING THE FOLLOWING
STRUCTURE:
- THE FIRST 8 BYTES SPECIFY THE COMMAND (SEE 2.3 FOR LIST OF COMMANDS)
- RESERVED 1 BYTE. CAN BE '*' TO IGNORE CARD
- NEXT 12 BYTES SPECIFY THE NAME FOR THE MODULE, SEE 2.4
- PADDING 1 BYTE.
- 6 BYTES FOR COLOR VALUE, SEE 2.6.
- PADDING 1 BYTE.
- NEXT 42 BYTES SPECIFY USER-DEFINED DATA, SEE 2.4.
- EVERYTHING ELSE IS IGNORED AND HISTORICALLY IS USED FOR LINE NUMBERS

/

===== LIST OF SUPPORTED COMMANDS

STATUSLINE SUPPORTS THE FOLLOWING LIST OF COMMANDS:
- '********' COMMENT COMMAND IS USED FOR MARKING THE RECORD AS COMMENT.
             THE REST OF THE RECORD IS SIMPLY IGNORED.
- 'GENERAL ' GENERAL COMMAND USED FOR SPECIFYING GLOBAL SETTINGS SUCH
             AS TIME FORMAT AND POLLING INTERVAL. THE COLOR AND NAME
             COLUMNS ARE IGNORED. HAS THE FOLLOWING FORMAT:
             - FIRST 3 NUMBERS SPECIFY POLLING INTERVAL
             - PADDING BYTE
             - 8 BYTES FOR THEME NAME, SEE 2.5.
- 'MODULE  ' MODULE COMMAND USED FOR ADDING MODULES FOR A STATUSLINE.
             FOR A MORE DETAILED MODULE SPECIFICATION, SEE 2.4.


===== LIST OF SUPPORTED MODULES

STATUSLINE SUPPORTS THE FOLLOWING MODULES:
- 'SYSTEM      ' SYSTEM MODULE IS USED FOR RUNNING EXTERNAL COMMAND.
                 THE SYSTEM MODULE INTERNALLY INVOKES:
                     "/bin/sh/" "sh" "-c" USER_SECTION
                 THE SYSTEM MODULE PIPES OUT STDOUT AND READS THE PIPE
                 FOR THE CHANGES, YOUR APPLICATION SHOULD WRITE TO THE
                 PIPE ONCE PER UPDATE.
                 IF THE CHILD CLOSES THE PIPE (OR EXITS) THE SYSTEM
                 MODULE OUTPUTS LAST READ FROM THE PIPE.
- 'BATTERY     ' BATTERY MODULE OUTPUTS THE CURRENT BATTERY PERCENTAGE.
                 THE OPERATOR IS REQUIRED TO PROVIDE PATH TO BATTERY
                 UEVENT DSN IN THE USER SECTION. THE LAST BYTE IN THE
                 USER SECTION SPECIFIES THE OUTPUT TYPE:
                 - 'C': CAPACITY
- 'MEMORY      ' MEMORY MODULE OUTPUTS THE CURRENT MEMORY USAGE AND ALL
                 OF THE AVAILABLE MEMORY.
                 ACCEPTS FOLLOWING COMMANDS IN USER SECTION:
                 - 'USED'
                 - 'TOTAL'
                 - 'FREE'
                 - 'AVAILABLE'
/
- 'LOAD        ' LOAD MODULE OUTPUTS THE CURRENT SYSTEM LOAD.
                 ACCEPTS FOLLOWING COMMANDS IN USER SECTION EITHER '1M',
                 '5M' or '15M'.
- 'DATE        ' DATE MODULE OUTPUTS THE CURRENT DATE IN THE FORMAT OF
                 DD/MM/CCYY. FOR THE KNOWN ISSUES, SEE 4.1.1. ACCEPT THE
                 CENTURY SELECTOR AS A TEMPORARY FIX OF THE CURRENT
                 ISSUES.
- 'TIME        ' TIME MODULE OUTPUTS THE CURRENT TIME IN THE FORMAT OF
                 HH:MM:SS. ACCEPTS EITHER 24H or 12H.
- 'TEXT        ' TEXT MODULE DISPLAYS TEXT PROVIDED IN THE USER SECTION
- 'SPACE       ' SPACE MODULE PRINTS EXACTLY SINGLE SPACE CHARACTER.
- 'SEPARATOR   ' SEPARATOR MODULE IS USED TO SEPARATE MODULES AND
                 CURRENTLY SUPPORTS FOLLOWING STYLES:
                 - '<' IN USER SECTION FOR BLOCK SEPARATOR
                 - '>' IN USER SECTION FOR BLOCK SEPARATOR
                 - "=" IN USER SECTION FOR CLASSIC BAR SEPARATOR
                 THE LAST BYTE IN THE USER SECTION IS THE ENCODING
                 SELECTOR AND SUPPORTS:
                 - 'A' FOR ASCII ENCODING
                 - 'E' FOR EBCDIC ENCODING
                 - 'U' FOR NATIONAL ENCODING WITH UNICODE
                 DEFAULT: 'E'
- 'TAPE        ' TAPE MODULE DISPLAYS THE STATUS OF THE BLOCK DEVICE
                 PROVIDED BY THE USER SECTION. THE LAST BYTE IN USER
                 SECTION DEFINES THE MODE:
                 - 'B': NUMBER OF BLOCKS. IN HUMAN READABLE BYTES
                 - 'R': FRAGMENT SIZE.
                 - 'L': NUMBER OF BLOCKS.
                 - 'H': NUMBER OF FREE BLOCKS.
                 - 'A': NUMBER OF BLOCKS AVAILABLE TO NORMAL USERS.
                 - 'F': TOTAL NUMBER OF INODES.
                 - 'E': NUMBER OF FREE INODES.
                 - 'I': TAPE ID.
                 - 'N': MAXIMUM NAME OF A DATA SET
- 'PATH        ' PATH MODULE DISPLAYS 'DOES EXIST' OR 'NOT EXIST '
                 WHETHER DSN PROVIDED BY THE USER SECTION IS VALID.
- 'JOBS        ' DISPLAYS THE NUMBER OF JOBS MAINFRAME IS PROCESSING.
                 UNSUPPORTED ON PERSONAL COMPUTERS.


FOR AN EXAMPLE CONFIGURATION SEE FILE 'STATUSLINE-COB.CFG'.

/

===== LIST OF THEMES

CURRENTLY STATUSLINE SUPPORTS FOLLOWING THEMES:

- 'ROSEPINE': (MAIN  VARIANT) SOMETHING BEAUTIFUL
              ALL NATURAL PINE, FAUX FUR AND A BIT OF SOHO VIBES FOR
              THE CLASSY MINIMALIST.
- 'GRUVBOX ': (DARK  VARIANT) MODERN GROOVE COLOR SCHEME
- 'SOLARIZE': (LIGHT VARIANT) PRECISION COLORS FOR MAINFRAMES AND OPERATORS

===== LIST OF SUPPORTED COLORS

- 'PRIM  ' ALSO KNOWN AS PRIMARY
- 'SECOND' ALSO KNOWN AS SECONDARY
- 'TERNRY' ALSO KNOWN AS TERNARY
- 'WHITE ' PURE WHITE
- 'BLACK ' PURE BLACK
- 'CIRNO ' OR ICE-BLUE-ISH
- 'LOVE  ' OR 'RED   ' OR 'SCARLE'. PER FAVORE AMA TUTTI.
           NOTE: THAT SINCE SCARLET IS LARGER THAN 6 BYTES YOU
           TECHNICALLY CAN WRITE LAST T INTO THE PADDING CHARACTER
- 'GOLD  ' OR 'YELLOW' LEMON TEA ON A SUMMER MORNING.
- 'ROSE  ' A BEAUTIFUL YET CAUTIOUS BLOSSOM.
- 'PINE  ' OR 'GREEN ' FRESH WINTER GREENERY.
- 'FOAM  ' OR 'BLUE  ' SALTWATER TIDE POOLS.
- 'IRIS  ' OR 'MAGENT', SMELL OF GROUNDEDNESS.
           NOTE: MAGENTA IS ALSO LARGER THAN 6 BYTES SO YOU CAN WRITE A
           IN THE PADDING CHARACTER.

===== ABEND CODES

S806: MODULE NOT FOUND                 THE STATUSLINE FAILED TO LOAD THE
                                       MODULES INIT HANDLER.
FMDMEM01: INVALID MEMORY FLAG          YOU SPECIFIED WRONG FLAG FOR THE
                                       MEMORY MODULE.
FMDSYS01 THRU FMDSYS04:                INDICATES INTERNAL ERROR AND MOST
                                       OF THE TIME INDICATES OPERATING
                                       SYSTEM FAULT.
EMDSYS01: RUNTIME ERROR                SYSTEM MODULE FAILED TO READ FROM
                                       PIPE.
EMDTPE01: RUNTIME ERROR                YOU SPECIFIED WRONG FLAG FOR THE
                                       TAPE MODULE.

=======================================================================
=======================  COMPILING THE PROJECT  =======================

===== LIST OF SUPPORTED STANDARDS

/

CURRENTLY, STATUSLINE IS WRITTEN IN GNU COBOL WITH IBM COBOL
STANDARD FLAG ALTHOUGH NOT BEING COMPLETE IBM COBOL, THIS STANDARD FLAG
PREVENTS SOME BACKWARDS COMPATIBILITY ISSUES.

===== COMPILING THE PROJECT

THE STATUSLINE IS COMPILED USING THE BUILD.EXEC FILE LOCATED IN THE
ROOT OF THE PROJECT. EXAMINE THE SCRIPT IN CASE YOU WISH TO COMPILE THE
PROJECT MANUALLY WITH COMPILER THAT IS DIFFERENT FROM A GNU COBOL.

DEPENDENCY OF STATUSLINE:
- LIBC
- LINUX (ABOVE 2.6.0)
YOU ALSO WOULD NEED A REXX INTERPRETER FOR RUNNING THE COMPILATION 
SCRIPT.

=== COMPILING USING NIX

IF IT HAPPENS SO THAT YOU CAN COMPILE THE PROJECT USING NIX THE PACKAGE
MANAGER YOU CAN USE THE FLAKE OR THE DEFAULT.NIX FILE PLACED IN THE ROOT
OF THE PROJECT.

========================================================================
==============================  HACKING  ===============================

THIS SECTION IS MEANT FOR ADVANCED USERS WHO WISH TO CUSTOMIZE THE
STATUSLINE-COB TO SUIT THEIR NEEDS MORE AND HELP THE PROJECT.

FOR ADDING NEW COLORS YOU CAN REFER TO THE 'COPYBOOKS/GET-THEME.CPY'.
WARNING: YOU ALSO MIGHT WANT TO MAKE NEW COLORS CONFIGURABLE VIA
         THEMING. TO DO SO YOU NEED TO MODIFY 'COPYBOOKS/THEMES-INIT.CPY'.

LIST OF CURRENTLY SUPPORTED PROTOCOLS:
|               NAME                   | IDX
| PLAIN TEXT                           |  1
| I3BAR                                |  0
| SWAYBAR                              |  0

IF YOU WISH TO ADD SUPPORT FOR YOUR PROTOCOL LOOK INTO
'SRC/AUTO-DETECT.CBL' AND ADD CUSTOM FORMATTING INTO 'SRC/OUTPUT.CBL'.

CHECK THE PERFORMANCE OF THE STATUSLINE USING 'bench.sh' SCRIPT IN THE
ROOT OF THE PROJECT.

/

===== KNOWN ISSUES

=== Y2K
THE DATE MODULE HAS A Y2K BUG, AND AS A TEMPORARY FIX YOU NEED TO
SPECIFY EITHER 'Y2K', 'Y2.1K' or 'Y2.2K'.


===== WRITING MODULES

STATUSLINE LOADS MODULE BY FIRSTLY TRYING TO CALL MOD_(MOD-NAME)_INIT
(NAME OF THE MODULE PREFIXED WITH 'MOD_' AND POSTFIXED WITH '_INIT')
USING THE DATA BUFFER WHICH PROGRAM CAN USE TO STORE DATA NEEDED FOR
MODULE EVALUATION, THE _INIT PROGRAM IS EXPECTED TO RETURN A NUMBER
SPECIFYING THE PROTOCOL FOR THE MAIN MODULE ENTRY POINT. IN THE MAIN
LOOP STATUSLINE WILL TRY TO CALL THE MOD_(MOD-NAME) (NAME OF THE MODULE
PREFIXED WITH 'MOD_') USING THE ARGUMENTS DEFINED BY THE PROTOCOL
VERSION SPECIFICATION, THE MODULE SHOULD PRINT THE DATA TO SYSOUT. SEE
IMPLEMENTATION OF MODULES IN 'src/modules/'. THE LENGTH OF A DATA BUFFER
GUARANTEED TO BE LONGER THAN 72 BYTES.

MODULE PROTOCOL VERSION SPECIFICATION:
VERSION | DESCRIPITON
0       | STUB FOR OLD MODULES, AND WILL BE REMOVED IN THE FUTURE
1       | CALL THE MODULE ENTRY POINT USING THE VALUE OF USER SECTION
2       | CALL THE MODULE ENTRY POINT USING THE REFERENCE TO DATA BUFFER
2       - PASSED IN THE INITIALIZATION STEP
3       | CALL MODULE WITHOUT WRAPPING IT IN OUTPUT BLOCK
4       | SAME AS 3, BUT USES FIRST 16 BYTES AS THE NEW ENTRY POINT FOR
4       - MODULE INSTEAD OF MOD_(MOD-NAME)

EXAMPLE TEXT MODULE: '''COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. MOD_TEXT.
       DATA DIVISION.
       LINKAGE SECTION.
       01 L-DATA                       PICTURE IS X(42).
       PROCEDURE DIVISION USING BY REFERENCE L-DATA.
           DISPLAY FUNCTION TRIM(L-DATA) WITH NO ADVANCING
           END-DISPLAY
           GOBACK.
       END PROGRAM MOD_TEXT.
       IDENTIFICATION DIVISION.
       PROGRAM-ID. TEXT_INIT.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01 L-BODY              EXTERNAL PIC IS X(42).
       LINKAGE SECTION.
       01 L-DATA                       PICTURE IS X(42).
       PROCEDURE DIVISION USING BY REFERENCE L-DATA.
           MOVE L-BODY                 TO L-DATA
           SET RETURN-CODE             TO 2
           GOBACK.
       END PROGRAM TEXT_INIT.
'''

===== TO DO LIST
- (X) DISPLAY TIME
- (X) DISPLAY LOAD
- (X) DISPLAY MEMORY
- (X) DISPLAY BATTERY
- ( ) DISPLAY NETWORKING
- (X) ADD MORE CONFIGURATION OPTIONS
- ( ) IMPROVE WTO SYSTEM