Banner Decode Exit Procedure Specification

A description of the exit procedure to be used to parse host output banner pages is given below.




	NOTE: In NRJE/XL, the Banner Decode Exit Procedure is called the Writer Decode Exit Procedure Specification.

Syntax

                           LA          BA         I        I 
Procedure NRJEBANNER(UserWorkArea, DataLine, LineLength, Cctl, 
                           I         BA       I       I 
                       RecordType, Jobnum, Filenum, Action)




	NOTE: The procedure name is identified in the NMMGR Writer Data screen for the applicable writer and need not necessarily be called `NRJEBANNER`.

Parameters

UserWorkArea: A logical array for input/output (of 100 words). UserWorkArea can be used for global storage; its size is from 0 through 99. This parameter is initialized to zeros by NRJE, but it is not subsequently modified by NRJE.
DataLine: An input byte array containing one logical record from the data set. This array will be decompressed and translated according to the configuration of the logical writer receiving the data set. For logical printers, the carriage control character is passed separately; it is not prefixed to the data line.
LineLength: A positive input integer variable (passed by value) indicating the number of bytes in DataLine. This does not include the carriage control character for print data sets, which is passed separately. A 0 indicates a blank line, and a -1 indicates that the end of the data set has been received.
Cctl: Input integer variable passed by value. This is the carriage control character for print data sets; it is set to zero for punch data sets.
RecordType: Input integer variable passed by value. This parameter is set to zero if DataLine contains a line of text from the output data set. If DataLine contains a PDIR, RecordType is set to one.
Jobnum: An output byte array (of 4 bytes). This array's size is from zero through three ASCII characters. Jobnum is initialized to ASCII blanks prior to each call of the exit procedure. If successful in decoding the host banner, the exit procedure is to return the job number in ASCII, left-justified, padded with blanks if necessary. If the exit procedure detects a banner indicating the output is from a "Started Task" (denoted by "STC" in the banner) or a "Timesharing User" (denoted by "TSU"), the procedure should indicate a job number consisting of these ASCII characters: minus, one, blank, and blank. This indicates that the banner decoding was successful, but NRJE should not check the Job Log for output routing information. This is because all "TSU" and "STC" jobs are unsolicited, and valid output routing information cannot be found in the Job Log for this job.
Filenum: Output integer parameter (passed by reference). Used only if the procedure will open the output file for NRJE rather than return a job number. (If Jobnum is returned as non-blank and Filenum is returned as non-zero, Jobnum is ignored and output is routed to Filenum.) Filenum is initialized to zero by NRJE prior to each call to the exit procedure.
Action: Output integer. Action is initialized to zero by NRJE prior to each call to the exit procedure. It is read only if the exit procedure sets a value for Jobnum or Filenum. If zero is returned, NRJE writes the saved banner to the output file. If Action is set to any other value, NRJE will not write the saved banner.

Description

The exit procedure name is specified in the NMMGR Writer Data screen. A different procedure can be accessed by each logical writer.

Note that the banner decode exit procedure is optional, and need not be specified unless NRJE's internal banner decode algorithm and output routing mechanism are not sufficient.

Refer to "Banner Decode Parsing Algorithms," earlier in this chapter, for additional information.

The exit procedure can implement any one of three functions:

Provide the host job number by decoding the data set banner. This enables NRJE to check the Job Log for output disposition information for the job.
Open the output file for NRJE by returning Filenum rather than Jobnum. NRJE then writes the data set to the file.
Open and write the entire data set to the output file. This is accomplished by not setting either of the output parms (Filenum or Jobnum), which causes NRJE to pass the entire data set to the procedure. FWRITE error handling is then the responsibility of the procedure.

The exit procedure will be passed each record of a received data set, beginning with the PDIR, until the procedure returns a non-blank value for Jobnum, a non-zero Jobnum, or a non-zero value for Filenum. If either value is returned by NRJE, NRJE will not call the exit procedure again until the next data set is received, except for this condition:

If a PDIR is received for which:

FORM name has changed, or
FCB name has changed, or
number of copies has changed, or
number of copies is not 0,

then the exit procedure will be called again. If the procedure returns a job number or file number to NRJE, the original file will be closed and the new output file will be used.

If the DataLine passed is a data record, the data line will be decompressed and translated as specified by the logical writer receiving the data set. If the received DataLine is a PDIR, the first four bytes will be passed without translation, and the remaining bytes in the record will be translated using the Native-3000 EBCDIC-to-ASCII translation table.

NRJE will save each banner line in an internal data structure, up to a maximum of 1024 lines.

If Jobnum is not blank, nor is it the "minus, one, blank, blank" ASCII character string, NRJE accesses the Job Log to determine the proper output destination. The saved banner lines are printed if Action is returned with a value of zero; otherwise, the saved banner lines are not printed. Allowing for the one exception described above, no subsequent calls are made to the exit procedure until the next data set is received.

If Filenum is not zero, NRJE writes the data set to the file opened by the exit procedure. If Action is returned with a value of zero, the saved banner lines are printed; otherwise, the saved banner lines are not printed.

If both Jobnum and Filenum are returned by the exit procedure, NRJE uses Filenum to route the data set and ignores Jobnum. Action is interpreted as described above.

If neither Filenum nor Jobnum is returned, NRJE passes the entire data set to the procedure and logs a warning message. NRJE assumes that the exit procedure is handling all output routing and writing operations.

If an exit procedure opens an output file by using the COMMAND intrinsic to execute a file equation, and then uses an FOPEN that back-references the file equation, it should also issue a RESET (using the COMMAND intrinsic) to remove the file equation before returning to NRJE. This is required to minimize the possibility of NRJE misrouting output on other writers.

For "End of Data Set" calls to the exit procedure (line length of -1), the returned values for Filenum and Jobnum are ignored.

This hierarchy is used to resolve any routing specification conflicts:

          Banner Decode Filenum return
                         overrides
          Job Log routing information (SUBMIT command parms)
                         overrides
          Lookup Table form-to-file mapping (user's JCL "FORM"
          specification)
                         overrides
          Defaults.

The procedure will be called by the SNA NRJE Logical Unit, which will be running with traps on, in user mode. The NRJELU is "prepped" with PM, PH, DS, MR, IA, and BA capabilities.

An SPL example of a banner decode exit procedure for use with JES2 banners is shown below. This example is also in the SAMPEXIT sample file in NRJE.SYS.

Example

procedure get'jobnumber(work'area,record,length,cctl,type,jobnumber,
                        file'num,action);
value length,cctl,type;
 
logical array work'area;        ! In, scratch area.
 
byte array record;              ! In, a line of data (or a PDIR) from
                                ! the host.
 
integer  length,                ! In, num bytes in record.
 
         cctl,                  ! In, carriage control value.
 
         type;                  ! In, if 0 record is data, if 1 record
                                ! is a PDIR.
 
byte array job number;          ! Out, the host job number.
 
integer    file'num,            ! Out, we won't set this.
 
           action;              ! Out, also not set.

###########################################################
!
! This procedure will decode a JES2 host banner and return the job
! number.  We do not open the output file here but let the NRJE LU
! handle the fopen and fwrites to the output file.
! If we received an "STC" or "TSU" job we return a job number of "-1"
! to cause NRJE to suppress its search of the Job Log (such data sets
! are unsolicited and will not have an entry in the job log).
!
! The banner we are checking looks something like this:
!
! *A START JOB nnnn jobname  . . . misc. other information
!          |
!          |--------- JOB'STRING'POS
!
! The first byte is byte "0", JOB'STRING'POS is a byte offset of
! the string "JOB" or "STC" or "TSU" which is followed by one or
! more blanks and then the job number.
!
############################################################
end of comment;
 
begin             ! Local declarations.
 
equate JOB'STRING'POS = 9,
       DATA'RECORD    = 0;
 
byte pointer bptr;
< ********************* Begin Get'Jobnumber ******************* >
 
if type = DATA'RECORD then
  begin
    if record(JOB'STRING'POS) = "JOB" then
      begin                        ! A hit.
        scan record(JOB'STRING'POS + 3) while "  ",1;
        @bptr := tos;              ! Skip any leading blanks.
        move job number := bptr while N;    ! Move while numeric.
      end                          ! If "JOB" found.
    else
      if record(JOB'STRING'POS) = "STC" or   ! Check for Started Task
         record(JOB'STRING'POS) = "TSU" then ! and Time Sharing User.
        move job number := "-1  ";
  end;                             ! If data record received.
 
! Else if PDIR record we'll just ignore it.
 
end;              ! Get'Jobnumber

Banner Decode Exit Procedure Specification

Technical documentation

» Table of Contents

» Glossary

» Index

Syntax

Parameters

Description

Example