HP 3000 Manuals HP 3000 Manuals
User Exits Two exits have been added to SNA NRJE to facilitate job management and output management operation. One exit calls a customer's procedure that decodes the host banner (separator page) and informs NRJE of the host job number for the data set. A separate exit procedure can be specified for each logical writer. A second exit passes all console data to a customer's procedure that parses the host "Job Received" messages sent by the host to the remote console when a job is submitted.
NOTE If an exit procedure is not specified, NRJE uses its own internal parsing algorithms to decode banners and "Job Received" messages. The exit procedures are not necessary unless the host has been modified to send nonstandard banners or console messages.
Configuration These two steps must be performed to configure SNA NRJE to access an exit procedure: 1. Install the procedure segment from the USL file into SL.NRJE.SYS. 2. Identify the name of the console exit procedure in the NMMGR Workstation Data Page 2 screen and the banner decode procedure (s) in the NMMGR Writer Data Screen. 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: 1. 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. 2. Open the output file for NRJE by returning Filenum rather than Jobnum. NRJE then writes the data set to the file. 3. 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. comment ########################################################### ! ! 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 "Job Received" Message Exit Procedure A description of the exit procedure to parse the console stream for a "Job Received" message is shown below; the message is HASP100 for JES2 and IAT6101 for JES3. Syntax ____________________________________________________________________________ | | | | | LA BA I I | | Integer Procedure CON(UserWorkArea, ConsoleRecord, Length, ReaderNum,| | BA BA | | Jobnum, JobName) | ____________________________________________________________________________ Function Return: Integer (-32768 through 32767). Procedure should return 1 if a "Job Received" message is detected; otherwise, the procedure should return 0. Parameters UserWorkArea Logical array for input/output (of 100 words). This array is initialized to zeros by NRJE, but it is not subsequently modified by NRJE. UserWorkArea can be used for global storage. ConsoleRecord An input byte array containing a console message from the host. ConsoleRecord is decompressed and translated into ASCII, using the Native-3000 EBCDIC-to-ASCII translation table. Length Input (positive) integer (passed by value). This contains the number of bytes in ConsoleRecord. ReaderNum An output integer value (passed by reference). The number of the logical reader (1 through 7) for which the "Job Received" message was received. The exit procedure is responsible for translating the ASCII value of the reader number into an integer value, using the BINARY intrinsic. If the host subsystem is JES3, this value should be set to 0, because JES3 "Job Received" messages do not contain a reader number. Jobnum An output byte array (of 4 bytes). Jobnum is initialized to blanks by NRJE prior to each call to the exit procedure. If ConsoleRecord contains the "Job Received" message from the host, Jobnum is to be returned here, left-justified (four bytes maximum). JobName Output byte array (of 8 bytes). JobName is initialized to blanks prior to each call to the exit procedure. If the procedure detects a "Job Received" message, it is to return the name of the job to JobName, left-justified. Description The procedure is identified in the NMMGR Workstation Data screen. If the procedure is not specified, an internal algorithm is used to parse the message. This algorithm will work unless the host job entry subsystem has been modified. If the procedure detects a "Job Received" message from the host, it is to return the integer value of 1 and the corresponding job number and job name. Any other function return value (!=) is ignored by NRJE. The procedure is called by the NRJELU in user mode, with traps on. The NRJELU is prepped with IA, BA, DS, MR, PH, and PM capabilities. An example of a console exit procedure in SPL to parse a JES2 HASP100 message is shown below. Example integer procedure parse'jes2'console(work'area,record,length, rdr'num,job number,jobname); value length; logical array work'area; ! In, scratch area. byte array record; ! In, the console record. integer length, ! In, positive byte count of record. rdr'num; ! Out, range 1 to 7 if HASP100 ! detected. byte array job number, ! Out, set if HASP100 detected. jobname; ! Out, set if HASP100 detected. comment ########################################################### ! ! Scans the console record from the host and checks for whether a ! HASP100 (Job Received message) was received from the host. Returns ! reader number, job number and jobname if HASP100 detected. ! ! The format of the console message is as follows: ! ! hh.mm.ss JOB nnnn $HASP100 jobname ON Rxx.RDy username ! JNUM'POS --| | | | ! HASP'POS -------| | | ! JNAME'POS ---------------| | ! RDR'POS ------------------------------------| ! ! All "POS" offsets are byte offset equates. The first byte is ! byte "0". ! ########################################################### end of comment; begin ! Local declarations equate CR = %15, ! Carriage return; scan terminator BLANK = %6440, ! Blank and CR, for scanning. ON'RDR'MSG = 1, ! Function return if HASP100 detected. HASP'POS = 18, ! Location of $HASP100 JNAME'POS = 27, ! Where jobname should be located. JNUM'POS = 13, ! Location of job number. RDR'POS = 45; ! Location of the reader number. byte pointer bptr; byte array hold(*) = work'area; define hold'byte = hold(0)#; ! Temp storage for last char of ! record(length). intrinsic binary; < **************** Begin Parse'JES2'Console ******************** > parse'jes2'console := 0; ! Initialize if length < RDR'POS then ! Don't bother to check if it's not return; ! long enough. hold'byte := record(length); ! We don't know what's here, so we'll record(length) := CR; ! save it and replace it with a known ! character for scanning. ! Scan for the host command char and string "HASP100": if record(HASP'POS) = "$HASP100" then begin ! It's a hit! ! Need to skip leading blanks, if any, so that what we return is ! left justified. scan record(JNAME'POS) while BLANK,1; @bptr := tos; move jobname := bptr,(scan bptr until " "); ! Move until blank. scan record(JNUM'POS) while BLANK,1; @bptr := tos; move job number := bptr while N; ! Move while numeric. rdr'num := binary(record(RDR'POS),1); parse'jes2'console := ON'RDR'MSG; end; ! Now put that "hold" byte back: record(length) := hold'byte; end; ! Parse'JES2'Console.