PL1TAX
Documentation

 

Commands

PL1TAX is a utility used primarily to produce cross-tabulations from flat files. PL1TAX can also be used to produce sorted, multi-column, control break listings. It can also be used for file processing, such as copying, filtering, and reformatting data files.

THEORY:

PL1TAX is actually a macro processor that generates a proper PL/1 program from user supplied statements. PL1TAX reads in input file, one record at a time, and processess each record subject to user supplied parameters.

STRUCTURE:

A PL1TAX program consists of sections. Each section has a valid set of parameters. Sections are denoted by the construct *SECTION. The valid sections are:

SECTION NAME         ABREVIATION
-------------------- -----------
*FILES               *F  
*FUNCTIONS           *FU 
*WORKINGSTORAGE      *WS 
*RECORDS             *RC 
*VARIABLES           *V  
*INITIALIZATION      *INIT     
*READ  
*CBREAD
*COPY  
*MATCH 
*MERGE 
*UPDATE
*INSTRUCTIONS        *I  
*TERMINATION         *TERM     
*TABLES              *T  
*REPORTS             *R

Of the above, only the *FILES section is required. For practical purposes, at least *INSTRUCTIONS, *TABLES, or *REPORTS should be included.

Of the sections appearing in a PL1TAX program, they MUST appear in the above order.

COMMANDS:

These are the valid commands within each section:

  (GENERAL LANGUAGE RULES)

  *FILES 
  
    SCREEN      - DEFINE THE OUTPUT PAGE FORMAT 
    PAGECT      - PAGE COUNTING PARAMATER 
    TITLE       - DEFINE TITLE FOR EACH PAGE OF OUTPUT
    OLD         - DEFINE THE MAIN INPUT FILE    
    LIMIT       - LIMIT THE # OF INPUT RECORDS READ   
    TRAN        - DEFINE THE TRANSACTION INPUT FILE   
    NEW         - DEFINE THE NEW OUTPUT FILE    
    OUTPUT      - DEFINE OUTPUT FILES     

  *FUNCTIONS

    LOOKUP      - INITIATE LOOKUP DEFINITION    
    END         - TERMINATE LOOKUP DEFINITION   
    GEN         - DATA GENERATION FUNCTION

  *WORKINGSTORAGE 

    VAR//       - DEFINE A VARIABLE 

  *RECORDS  

    VAR//       - VARIABLE DEFINITION     
    TRAN        - TRAN VARIABLES FOLLOW   
    NEW         - NEW  VARIABLES FOLLOW   

  *VARIABLES
    VAR//       - DEFINE A VARIABLE 

  *INITIALIZATION (SEE *INSTRUCTIONS)     

  *INSTRUCTIONS   

   REPLACEMENT: 
  
    RECODE      - CHANGE VALUE OF VARIABLE
    SET         - COMPUTE NEW VALUE OF NUMERIC VARIABLE     
    TRANSLATE   - REPLACE ONE SET OF CODES WITH ANOTHER     
    TRANSFORM   - REPLACE ONE SET OF CHARACTERS WITH ANOTHER
    LOOKUP      - UTILIZE TABLE LOOKUP FUNCTION 
    GEN         - ACTIVATE THE GEN FUNCTION     
    MODIFYFIELDS- USED IN *UPDATE SECTION.
    NNZERO      - NUMERIC PROTECTION MACRO

   DIRECTIVES:    
    SUBTITLE    - DEFINE SUBTITLE FOR ALL PRINT DIRECTED OUTPUT  
    PRINT       - OUTPUT DATA TO PRINTER  
    WRITE       - OUTPUT DATA TO FILES    
    PAGE        - PAGE EJECT  
    TABLE       - CALL A TABLE
    REPORT      - CALL A REPORT     

   CONTROL: 

    SELECT      - DEFINE RECORD SELECTION (GLOBAL)    
    IF          - DECISION LOGIC    
    ELSEIF      - "     
    ELSE        - "     
    ENDIF       - TERMINATES IF STATEMENT 
    NOSELECT    - SET NONSELECT CONDITION 
    RETURN      - EXIT WITH SELECT CONDITION    
    CALL        - CALL A SUBROUTINE 
    SUBROUTINE  - DEFINE A SUBROUTINE     
    END         - END A SUBROUTINE  
    GOTO        - UNCONDITIONAL TRANSFER  
    TAG.        - ADDRESS    
 
  *TERMINATION    (SEE *INSTRUCTIONS)     

  *TABLES   

    PERCENTS    - TABLE OPTIONS (GLOBAL TO *TABLES)   
    ZERO LINES  - "     
    PAGES       - "     
    TABLE       - TABLE HEADING DEFINITION
    FOOTNOTE    - TABLE FOOTNOTE DEFINITION     
    SELECT      - RECORD SELECTION (LOCAL TO THIS TABLE)    
    ACCUM       - ACCUMULATE NUMERIC VARIABLE   
    PERCENTS    - TABLE OPTIONS (LOCAL)   
    ZERO LINES  - "     
    PAGES       - "     
    STUB        - DEFINE STUB OF TABLE    
    ROW         - "     
    SPREAD      - DEFINE SPREAD OF TABLE  
    COLUMN      - "     
     
  *REPORTS  

    REPORT      - DEFINE REPORT HEADING   
    SELECT      - RECORD SELECTION (LOCAL TO THIS REPORT)   
    DOUBLESPACE - REPORT OPTION     
    TRIPLESPACE - REPORT OPTION     
    IMAGES      - DEFINE MULTIPLE IMAGES  
    IMHEADS     - MULTIPLE IMAGE HEADINGS 
    LIST        - VARIABLES TO BE LISTED  
    LISTAH      - VARIABLES TO BE LISTED (AUTOMATIC HEADINGS)  
    SORT        - VARIABLES TO SORT ON    
    PAGE        - VARIABLE TO PAGE ON     
    COLUMN      - VARIABLE TO COLUMN ON   
    DOUBLE      - VARIABLE TO DOUBLE SPACE ON

Of the above commands, the ones in *TABLES, and *REPORTS MUST appear in the above order.

GENERAL LANGUAGE RULES:

Naming conventions:

 Filenames:  1 to 12 alphanumeric beginning with alpha character.
 Variable names:  1 to 28 alphanumeric beginning with alpha character.
 String Literals:  Enclosed in single quotes (') up to 56 characters long.

Statements:

The following 3 statements are equivilant:

WRITE V1,V2,V3 ON D1

WRITE V1,V2,
      V3 ON D1

WRITE V1,V2,V3 ON @
      D1

The point being, statements may be broken on commas (,), or by use of the at (@) character.

Expressions; Logical and Computational:

Logical (true/false) expressions appear in:

SELECT
IF 
ELSEIF
ROW
COLUMN

The general form:

1. VAR REL VAR1
2. VAR REL S1,S2-S3,... (STRINGS)
3. VAR NUMERIC
4. VAR NNUMERIC         (NOT NUMERIC)

Where VAR is a variable, REL is in (EQ, NE, LT, LE, GE, GT) or (=, ^=, <, <=, =>, >). Strings need not be enclosed in ('). Examples:

V1 EQ CA
V2 EQ 'SAN FRANCISCO'
V1 EQ V2        (V2 MAY BE VARIABLE OR LITERAL)
V1 EQ 'V2'      (LITERAL 'V2')
V3 NE 0,2,4,6-9
V4 =  000,100-199,'** '

Computational expressions are mathematic expressions of the form:

V1 = MATH EXPRESSION

Where the expression contains literal numbers, numeric variables, and the symbols: + - * / ( ). Examples:

CEL = 9*(FAR-32)/5
MEG = KILO /1024

Headings:

The following commands are subject to heading rules:

TITLE
SUBTITLE
TABLE
FOOTNOTE
REPORT
IMHEADS

The general case of the heading expression is:

COMMAND NX,'LITERAL',/, ...    OR
COMMAND ='LITERAL',/, ...

Where NX means N spaces, LITERAL is a string, and / means next line. ='LITERAL' means center the LITERAL. Examples:

TITLE *'EVERY PAGE',/       * MEANS INCLUDE DATE AND PAGE # for TITLE ONLY

TABLE

TABLE 'TABLE #1'

TABLE ='STATE OF CA',/,='DEPT of JUSTICE',/

REPORT ='LISTING OF ALL',/,/,
       ='OUTSTANDING EMPLOYEES'

Picture clauses:

Picture clauses from COBOL and PL/1 (they are the same) may be used in PL1TAX programs. The restriction is, they may NOT use repeating expressions, they MUST be explicit. Use 99999 not 9(5).

 ALLOWABLE CHARACTERS    
 
      CLASS          MEMBERS  
      SIGN           S DB CR + -    
      EXPONET        E K
      DIGIT          9 I R T Y
      SUPRESSION     Z * $    
      INSERTION      . , / B V

 EXAMPLES:  

      *WORKINGSTORAGE   
       AMOUNTSPENT//P'$$,999.99'    
       BALANCE//P'$$,999.99CR'
       CHECKAMOUNT//P'$**,***.99'   

      *RECORDS    
       INCOME//51-56/P'99999'

      *INSTRUCTIONS
       PRINT RECORDDATE:'99/99/99',2X,AMOUNT:'$,$$$,999.99'

Direct in sertion of PL/1 code:

PL1TAX allows for the direct insertion of PL/1 code. Naturally this implies a burden on the writer. The code is preceeded by $PL1. Example:

*INITIALIZATION
$PL1 GET LIST(FROMDATE, TODATE);
...

*INSTRUCTIONS
$PL1  IF (INDEX(V1,'-')=0)
$PL1  THEN DO;
           NOSELECT
$PL1       END;

In the first case, two variables are requested, in the second case PL/1 is mixed with regular PL1TAX statements.

Commands

*FILES               *F

Valid commands:

SCREEN 
PAGECT 
TITLE  
OLD    
LIMIT  
TRAN   
NEW    
OUTPUT (OUT)

OLD:

Define the input file to the program. Formats:

1.  OLD CARDS
2.  OLD DISC/FILE D1 RL (V)   
3.  OLD TAPE T1 BLOCKED (BF*)RL (V (BLKSZ))
4.  OLD GENERATED (RL OR DEFINITION) 
5.  OLD MKEY M1 RL (V)

1. Input comes from cards or the system input.

2. Input comes from disc, named D1, RL record length, (V variable length).

3. Input comes from tape, named T1, RL record length, BF blocking factor, (V variable length (BLKSZ blocksize)).

4. Input comes from generated (used in testing).

5. Input comes from MKEY file.

Examples:

OLD FILE F1 80

OLD DISC D1 256 V

OLD TAPE T1 80

OLD TAPE SYS099 40*80

OLD GENERATED 40N

LIMIT:

Limit the number of records read. (Used in testing). Example:

LIMIT 1000
LIMIT 10000

TITLE:

Used to define a title for every page of output. See Headings.

OUTPUT (OUT):

Used to define an output file for the program. Examples:

OUTPUT DISC D2 100
OUTPUT TAPE T2 40*80
OUT FILE SYS077 256

 

Commands

*FUNCTIONS           *FU

 

Commands

*WORKINGSTORAGE      *WS

Workingstorage is for the defination of variables not part of the input files. The general command:

VAR/(VAR LABEL)/SPECIFICATION/(INITIAL VALUE)

Examples: (Numeric)

N1//N
N2//N6
N3//N/1
N4/TOTAL COUNT/Z6
N5/BINARY COUNTER/B
N6/TAX RATE/F
N7/SPECIAL PICTURE/P'$,$$$,999.99'

Examples: (Character)

A1//A
A2//A6
A3//A3/'ABC'
A4/ALPHABET MISSING/A26/'ABC',20x,'XYZ'
FOUNDSW//A/'F'

Variables may be redefined. The general command:

/VAR/(VAR LABEL)/SC(-EC)

Where / indicates redefinition, SC is the starting column, and EC is the ending column. Examples:

LPN/LONG DIST PHONE #/A11
/AREACODE//2-4

MMDDYY//A8
/DD/DAY OF MONTH/4-5

Commands

*RECORDS             *RC

Records is where variables are defined that are part of the input file. Note that only variables used by the program need be defined. Further note that columns may be defined in mutiple varaibles. Also note that there is an implied variable DATA that is defined as the whole input record. The general command:

VAR/(VAR LABEL)/SC(-EC)/(TYPE or PICTURE)

Some Examples:

DATA//1-RECORDLENGTH            - PREDEFINED

V1//1
V2//2-3
NAME/SUBJECT NAME/1-30
LN/LAST NAME/16-31
FLLN/FIRST LETTER LAST NAME/16
N1//6-9/N                       - NUMERIC
N2//6-9/P'9999'                 - EQUIVILANT TO ABOVE
Z1//4-9/P'ZZZ999'               - USES PICTURE

Here SC is starting column, EC is ending column, N indicates numeric (all numbers), and P indicates Picture Clause.

Commands

*VARIABLES           *V

Variables section defines varaibles that are functions of the input file. These variables are regenerated each time a record is read. The general command is:

VAR/(VAR LABEL/(SC(-EC)),NX,'LITERAL',...

These variables are composed of columns, spaces, and/or literals. Examples:

*RECORDS
 MMDDYY//6-11
 NAME//31-48

*VARIABLES
 YYMMDD//10-11,6-9
 SSN/SOCIAL SECURITY NUMBER/21-23,'-',24-25,'-'26-29
 BM/BLANK NAME/1-30,18X,49-80

 

Commands

*INSTRUCTIONS        *I

Instructions is the section which variable processing takes place. Variables may be compaired and modified. The valid commands:

REPLACEMENT:
  
  TRANSLATE    
  TRANSFORM    
  LOOKUP 
  GEN    
  MODIFYFIELDS 

DIRECTIVES:   

  SUBTITLE     
  PRINT  
  WRITE  
  PAGE   
  TABLE  
  REPORT 

CONTROL:

  SELECT 
  NOSELECT
  IF     
  ELSEIF       EF
  ELSE         EL
  ENDIF        NF
  RETURN 
  CALL   
  SUBROUTINE   
  END    
  GOTO   
  TAG.

Simple replacement:

VAR = VAR1,NX,'LITERAL',....
VAR = MATH EXPRESSION

Examples:

V1 = V2
V1 = 'CA'
YYMMDD = YY,'/',MM,'/',DD
CSQ = A*A + B*B

TRANSLATE: change a variables value from one set of codes to another. Examples:

TRANSLATE SEX FROM 1,2 to M,F
TRANSLATE OFFENCE FROM 101-110 to 201-210

TRANSFORM: change a variables characters from one set of character to another. Examples:

TRANSFORM V1 FROM 'ABC' to 'XYZ'
TRANSFORM V2 FROM '02468' to '13579'

Directives:

SUBTITLE is used for headings as output by PRINT statements in the *INSTRUCTIONS section. See Headings.

PRINT is used to print. The general command is:

PRINT VAR(:'PICTURE'),NX,'LITERAL',/,...

Where Var is a variable, : indicates a Picture Clause to follow, NX is n spaces, LITERAL is a literal, and / is a new line. Examples:

PRINT DATA
PRINT V1
PRINT 'EMPLOYEE NAME: ',NAME
PRINT NAME,/,ADDRESS,/,CSZ,/,/
PRINT 'IN THE AMOUNT OF: ',SUM:'$$$,999.99'

WRITE is use to write data to files. The general command is:

WRITE VAR(:'PICTURE'),NX,'LITERAL',... ON F1

Where Var is a variable, : indicates a Picture Clause to follow, NX is n spaces, LITERAL is a literal, and F1 is the file to be written to. Examples:

WRITE DATA ON F1
WRITE V1 ON SYS049
WRITE 'EMPLOYEE NAME: ',NAME on NAMEFILE
WRITE NAME,2X,ADDRESS,2X,CSZ ON ADDRFILE

PAGE

TABLE is used to call a labeled table. Examples:

TABLE T1
TABLE SUMS

REPORT is used to call a labeled table. Examples:

REPORT R1
REPORT SUMS

Control:

SELECT is used to filter records. If the SELECT statement is true processing continues, otherwise a new record is read. See Expressions. Examples:

SELECT STATE = CA
SELECT STATE = CA,NV,OR,WA
SELECT AMOUNT > 10000
SELECT LETTER = A,E,I,O,U

NOSELECT is used to cancel processing immediately. Example:

IF V1 = 'BAD'
   PRINT DATA
   NOSELECT
ENDIF

IF, ELSEIF (EF), ELSE (EL), ENDIF (NF) are used for decision processing. IFs may be nested. IFs must end with an ENDIF. See Expressions. The general command is:

IF EXP_1
ELSEIF EXP_2   - OCCURS 0 TO N TIMES
ELSE           - OCCURS 0 to 1 TIMES
ENDIF          - OCCURS      1 TIME

Examples:

IF SALARY > 50000
   PRINT DATA
ENDIF

IF COMPANY = IBM
   WRITE DATA ON IBMFILE
ELSE
   WRITE DATA ON OTHERFILE
ENDIF

IF AGE < 18
   PRINT NAME,' KID'
EF AGE = 19-22
   PRINT NAME,' COLLEGE'
EF AGE = 23-65
   PRINT NAME,' WORKER'
EL
   PRINT NAME,' RETIRED'
NF

IF COMPANY = CDC
   IF SALARY > 90000
      PRINT NAME,' GOOD'
   EL
      PRINT NAME,' NOT AS GOOD'
   NF
NF

Note that the abbreviations EF, EL, and NF add to the clarity of the IF statements.

Commands

*TABLES              *T

The valid table commands are:

TABLE 
FOOTNOTE    
SELECT
ACCUM 
PERCENTS    
ZERO LINES  
PAGES 
STUB  
ROW   
SPREAD
COLUMN

TABLE begins the table definition and defines a heading. See Headings.

FOOTNOTE defines the table footnote and follows the heading definition. See Headings.

SELECT allows for filtering records for this particular table. See Expressions.

ACCUM specifies a variable to be accumulated for a table. The default is count each occurance. Examples:

ACCUM SALARY
ACCUM CREDITS

PERCENTS specifies secondary tables are to be generated with percents calculated. The possibilities are:

PERCENTS ROWS,COLUMNS,ROW SUBTOTALS,COLUMN SUBTOTALS,GRAND TOTALS

Any or all may be specified.

ZERO LINES specifies that rows are to be printed even if their values are zero.

ZERO LINES

STUB defines the table stub. Up to 3 stubs may be defined. The general command is:

STUB VAR LABELS L1,L2,L3, ...    - OPTIONAL

STUB VAR CODES C1,C2,C3, ...     - or
STUB VAR GROUPS C1-C2,C3-C4, ...
-or-
STUB VAR N CODES

The stub labels is optional and applies to codes or groups. The N CODES is used to get the first N unique codes.

SPREAD defines the table spread. 0 or 1 SPREADs may be defined. The general command is:

SPREAD VAR LABELS L1,L2,L3, ...    - OPTIONAL

SPREAD VAR CODES C1,C2,C3, ...     - or
SPREAD VAR GROUPS C1-C2,C3-C4, ...
-or-
SPREAD VAR N CODES
-or-
SPREAD TOTAL

The SPREAD LABELS is optional and applies to CODES or GROUPS. The N CODES is used to get the first N unique codes. With SPREAD only 30 codes may be specified. TOTAL means no SPREAD, just the TOTAL column.

 

Commands

*REPORTS             *R

 

Commands