Job and Output Management

Job management is the ability to specify the final destination of the output at the time the job is submitted to NRJE to be transmitted to the host. NRJE accomplishes this through parameters included in the SUBMIT command which can directly or indirectly identify a final destination.

Output management is the ability to route output by specifying special forms for output data sets using file equation records in a lookup table. The Lookup Table is configured as part of SNA NRJE and keyed into through special form names specified in the job. The Lookup Table maps these special form names to file equations defining final destinations for the output.

The flow of data through these procedures is described next.

Job Output Data Flow Description

You submit a job within the SNA NRJE subsystem by using the SUBMIT command. As part of that command you may optionally specify PRINT, PUNCH, or FORMS output designations. PRINT and PUNCH designations provide control of output that is routed from the host to printer or punch devices, using the default or standard form name. These designations override JCL specifications for standard output.

FORMS designations provide control of output that is routed from the host to printer or punch devices, using any form name other than the default.

This SUBMIT command information is placed into a specially formatted Job Log record and is written to the NRJE reader along with your file. These parameters are defined in the SUBMIT command discussion in Chapter 3 “User Commands”.

When your workstation is active, the NRJE Logical Unit scans the NRJE reader for ready spool files. When the LU finds one, it copies the spool file to the host and waits for information containing the job's unique job number from the host. With JES2 and JES3 host job entry subsystems, the unique job number is supplied as part of a "Job Received" message that is returned when the host receives a job. The job number, along with other information in the formatted Job Log record, is written to a Job Log file that you configure for your NRJE workstation.

When an output data set is received from a JES2 host, the NRJE LU attempts to obtain the job number by scanning the output banner. For JES3, the job number is returned in the PDIR. When NRJE finds the job number, it checks the Job Log for routing information for the job, and updates a count of the number of data sets received for the job. If necessary, NRJE also checks the Lookup Table configured for NRJE for routing information. The special form names used to access the information from the Lookup Table are specified in the job stream or as part of the SUBMIT command. The special form name is sent back to NRJE in a PDIR generated by the host.

Job Management with the SUBMIT Command

Details for use of the SUBMIT command are in Chapter 3 “User Commands”

For job management to work, the NRJE subsystem must be able to obtain host job numbers from both "Job Received" messages and host output banner pages. For the JES2 host job entry subsystem, if standard messages and banners are generated, internal parsing algorithms (available with SNA NRJE) are used to obtain this information. For JES3, a parsing algorithm is used to obtain the job number from the "Job Received" message, but the output banner need not be scanned. The job number is transferred to NRJE from the host in the spin number field of the PDIR.

User exits are provided if you need to generate parsing programs to handle non-standard information coming from your host system. These exits and the algorithms for the NRJE-supplied parsing routines are described in Appendix A “Parsing Algoithms and User Exit Procedures”




	NOTE: If you are connected to a VSE/POWER host, the job number that is generated cannot be used to track the output data sets. As a result, use of the Job Log is not in effect for NRJE connected to VSE/POWER. Job management with the SUBMIT command is therefore not possible. The SUBMIT command is still used to make jobs available for transmission to the host.

With the SUBMIT command you can direct standard output with PR= or PU=, and special forms output with FO= options. In each field you can specify the following:

A formal file designator ( *filename).
A logical device class in double quotes ("DEVICE").
A logical device number (ldev), which is a numeric entry.
An actual file designator (alphanumeric, first character is alphabetic).
An alternate formid listed in the Lookup Table, surrounded by single quotes ('formid').

The routing information you specify is stored in the workstation Job Log. The Job Log consists of a KSAM data file and key file. The default names for these files are as follows:

NRJEJOB: KSAM data file containing a maximum of 10,000 records, with information about each job submitted.
NRJEKEY: KSAM key file used to access the data file. The elements are the job numbers for JES2 and JES3 that are returned from the host. Alternate keys are the UserName.AcctName of the user that submitted the job, and the host job name.

These names can be configured in the NMMGR Workstation Data Page 2 screen as described in the SNA Link Services Reference Manual or the SNA NRJE Node Manager's Guide. If multiple NRJE workstations are configured on your HP 3000, each workstation must be directed to access separate job and key files.

If you specified no alternate output destination parameters in the SUBMIT command, then output routing will depend on whether the optional output management Lookup Table is in use.

Output Management with the Lookup Table

This section describes an output routing feature of SNA NRJE that enables you to designate a final destination of an output data set by directing output to a special form name (formid). The special form name you specify is used to key into a Lookup Table which you generate. The Lookup Table contains file equation attributes to identify the output file.

Use of the Lookup Table is an optional feature of SNA NRJE. Note that output routed to the standard form is not controlled by the Lookup Table even if it is in use. Any entry in the Lookup Table under the standard form name is ignored for standard form output.

Description

To route output using special forms identifiers, you must specify special forms in your output data sets by using the appropriate job control language. A formid is any form name that identifies an entry in the Lookup Table. For example, if your NRJE installation is connected to a JES2 host, you could use the following:

`/*OUTPUT EPOC F=PYCK`	(JCL JES2 control statement)
with JCL DD statements like:
`// DD SYSOUT (A,,EPOC)`	(JCL data definition statement referring to a previous control statement)
	or
`// DD SYSOUT (A,,PYCK)`	(JCL data definition statement)

With either of the above DD statements, the applicable data set will be routed to special form PYCK. The form name is placed into the PDIR by the host system. When it receives the PDIR for the data set, NRJE will use the name of the special form PYCK to key into the Lookup Table. This table must be built by the NRJE manager and must contain all special formids supported at your remote, along with file equation attributes for each formid. SNA NRJE will open the output file based on the file equation attributes found in the table. An example Lookup Table entry is shown below under "Example Lookup Table Entry." Note that a sample Lookup Table file is provided in the SAMPTABL sample file in NRJE.SYS.

Creating the Lookup Table

The Lookup Table is a file created in the SYS account, and it contains the formid names and associated file equation attributes. To enable the Lookup Table feature, the NRJE manager must perform the following tasks:

Build the Lookup Table in the SYS account using an editor such as EDIT/3000 or TDP/3000.
Specify the Lookup Table file name in the field of the NMMGR Workstation Data Page 2 screen. (The default value is NRJETABL.NRJE.SYS.)

Format of Lookup Table Entries

The format you must use for the entries when creating or adding to the Lookup Table with the editor is as follows:

Columns 1-8:: formid names. Any combination of alphanumeric or IBM National Characters (#, $, or @), left-justified, padded with blanks if necessary. formid CMD is reserved.




	NOTE: If you have a `'formid'` in the Output Destination field of the writer screens, the Lookup Table entry can be only 6 characters. Although the screen field length is 8 characters, 2 of those characters are apostrophes (`' '`).

Columns 9-EOR:: File equation attributes as allowed by the MPE FILE command. See MPE Commands Reference Manual for details on the FILE command.

(EOR = End of Record; upper limit is 260 characters.)

In addition, the following rules apply to the Lookup Table entries:

The Lookup Table can be of any record width supported by the editor, to a limit of 260 bytes. 80 bytes are recommended to facilitate viewing the file on a terminal screen.
Continuation records are allowed, using the ampersand (&) as the last non-blank character.
Concatenated records cannot exceed 260 non-blank characters.
The file can be kept either numbered or unnumbered.
No distinction is made between upper and lower case characters.
An entry for each formid to be supported by the workstation must appear in the table. Each entry is limited to 6 characters if configured in the writer screen.
NRJE performs a linear search when accessing the table. If duplicate formids reside in the table, only the first one is used.

Example Lookup Table Entry

Column:
1	9
.
.
.
form?	;dev=epoc;env=lp602.hpenv.sys

NRJE will access the above entry whenever an output data set is to be printed on the form form7. That output will be routed to device EPOC using environment file lp602.hpenv.sys, unless you indicate different routing specifications with the SUBMIT command routing options.

Using the Lookup Table

At startup, SNA NRJE references the Lookup Table identified in the Formid Lookup Table File field in the NMMGR Workstation Data Page 2 screen. If this field is blank, NRJE will operate without a Lookup Table. If NRJE finds a Lookup Table configured in this field, but the file does not exist, NRJE terminates and the following message is displayed:

NRJE UNABLE TO OPEN LOOKUP TABLE. (MON=544)

Operation With the Lookup Table

Each workstation copies the Lookup Table into a temporary internal file. A linear search through the temporary file is performed whenever a data set requesting a special form is received. If a match is found, NRJE uses the corresponding file equation record to route the data set. If the formid is not found in the temporary file, NRJE opens the permanent file and checks to determine whether it has increased in size since the last access. If it has increased in size, NRJE will reload the internal temporary file and search again for the formid before going into error recovery.

In error recovery, NRJE issues an error message indicating the failure to locate the formid specified. If this formid cannot be found in the Lookup Table, NRJE will attempt to route output to the default destination with a priority of 2. This default destination is specified in the Output Destination field of the NMMGR Writer Data screen. See the SNA Link Services Reference Manual or the SNA NRJE Node Manager's Guide for the configuration procedures.

When using the Lookup Table, NRJE uses the default file system options for printer and punch streams as described in Table 3-3 “Default FOPEN Parameters” and the punch output differences following it. The output priority used is that configured for the applicable writer in the NMMGR Writer Data screen.




	NOTE: MPE has established a hierarchy to resolve potentially conflicting file system options: File equation attributes always override `FOPEN` specifications.

Lookup Table Examples

Each entry in the Lookup Table is identified by a formid in positions 1-8. The parameters following a formid function like a FILE command from MPE. Example Lookup Table entries are shown below in shaded text, with explanations after each.

I2      ;dev=EPOC,4,2;env=lplong.HPENV

This Lookup Table entry causes all output for form I2 to be routed to device class EPOC. The output priority is 4. Two copies are to be printed. The environment file is lplong.hpenv.sys. Note that no distinction is made between upper and lower case characters.

5927    ;DEV=LPS,,5;ENV=LP60LONG.HPENV

This causes all output for form 5927 to be routed to output device class LPS. The environment file is lp60long.hpenv.sys. Five copies are requested. The output priority used is the value configured in the NMMGR Writer Data screen for the writer receiving the output.

payroll ;DEV=EPOC,5,3;ENV=CHECKENV.HPENV;forms=checks.

This entry routes output for the special form PAYROLL to device class EPOC. The output priority is 5. Three copies are requested. The environment file is checkenv.hpenv.sys. When the spool file becomes active on the HP 3000, a forms mount message for the special form checks. is displayed on the system console. The period (.) in the forms parameter is required to designate a form.




	NOTE: The `forms` parameter should always be placed after the `env` parameter.

The formid PAYROLL has more than four characters. Some host systems support four characters or less for a special form name in their job control language. However, a user can direct forms output to this entry by using the SUBMIT command with solicited output:

SUBMIT filename;FORMS='PAYROLL'

disc =mydata.nrje,new

Output is routed to a disk file with the above entry. Output destined for the formid disc is sent to the disk file mydata.nrje.sys. The new parameter overrides the default value of old. NRJE builds the file for you.




	CAUTION: If the file already exists as a permanent file, NRJE cannot close the file successfully. In such cases the file is renamed as NRJEnnnn, where nnnn is a 24 hour time stamp. If the file cannot be renamed, the output is lost.

Files cannot be built across accounts. Use the new parameter to build files in the SYS account only.

disc2   =discS.nrje.myacct

This entry causes all output for the formid disc2 to be routed to disk file discs.nrje.myacct. This file must be built in advance. NRJE assumes that the file already exists unless the new parameter is specified. A new option could not be used here because NRJE cannot build files across accounts.

$@@long#;dev=pp;env=lp604.hpenv

A formid can begin with numeric or IBM national characters (as well as alphabetic characters) and can be up to eight characters long. Output routed to formid $@@long# is sent to device class PP using environment file lp604.hpenv.sys.

test    =special;dev=pp,3;forms=special.

This entry causes the output file to be named SPECIAL, rather than the host jobname. The device class is PP. The specified output priority is 3. The period (.) in the forms parameter is required to designate a form. The form name in this example matches the file name assigned to the spool file. This enables HP 3000 operators to more readily identify the names of special forms required by spool files, since the SHOWOUT output indicates the name of the form required.

frm1    =newfile ,new

This causes NRJE to build a new file in the NRJE logon group and account (NRJE.SYS) using the host jobname as the filename. This entry provides a mechanism for routing either solicited or unsolicited output to disk, and building a new file using the name of the job as the filename.




	CAUTION: You can do this only in `NRJE.SYS`. File equations of this type apply only to the logon group and account of the NRJE monitor stream job.

Always use a unique host jobname with this feature. Use of non-unique host jobnames may cause data to be lost in an attempt to create duplicate permanent files.

System Security Considerations

If the Lookup Table is used to route output to disk files, the node manager should ensure that users are not able to direct output to files for which they do not have legal access. Note that output is routed by NRJE running as a batch job under UserName.SYS. By obtaining the form name of a record in the Lookup Table which directs output to a disk file, a user can direct his output to this file, provided UserName.SYS has write access to the file (regardless of whether the user has access). To minimize the potential for abuse of system security, the node manager should use the MPE ALTSEC or ALTGROUP commands to ensure that only authorized users have read access to the Lookup Table.

Starting Jobs on the HP 3000 (Reverse NRJE)

The special formid CMD is reserved by NRJE. It is used to cause NRJE to stream a received data set rather than route the data set using file equation attributes. To cause job output to be streamed, you must do the following:

Route the output to a PUNCH device.
Prefix all MPE commands with an exclamation mark (!). The first data record must be a valid MPE JOB card.

It is not necessary to add an entry for CMD in the Lookup Table to use the reserved form. Also, the reserved form name CMD is used by all logical punches to stream output, regardless of whether the Lookup Table is in use.

Uses For Reverse NRJE

The following is a list of suggested uses of the Reverse NRJE feature:

Scheduling HP 3000 jobs from the host.
Querying the status of the HP 3000 from the host.
Submitting jobs to remote or local HP 3000s to access data and/or software available on those machines.
Gaining access to HP 3000 communications facilities (NS/3000, X.25, etc.).
Gaining access to HP 3000 peripherals (HP 268xx laser printer, reading STORE tapes, etc.).
Uploading and downloading files. (Due to limitations of the host subsystem, deblocking may be necessary.)
Performing postprocessing of data on the HP 3000 before printing.
Deferring printing.
Providing a method for routing unsolicited output to disk files without compromising system security. See "System Security Considerations" earlier in this chapter.
With Reverse NRJE, you do not have to route to a specially created formid in the Lookup Table. The output need only be routed to CMD on a punch device job stream. You do need to supply the appropriate logon passwords in your job.
Performing miscellaneous system management functions without having to physically go to the NRJE site. You could run FREE5, LISTLOG5, issue a SHOWJOB command and send the output back to the host, or start an HP 3000 system backup, etc.

Reverse NRJE Example

Below is an example of the use of Reverse NRJE which informs the HP 3000 operator that the host is about to disconnect.

//WARNALL JOB ,FORELL,MSGCLASS=A
/*ROUTE  PUNCH RMT1
/*ROUTE  PRINT RMT1
// EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=A
//SYSIN    DD DUMMY
//SYSUT2   DD SYSOUT=(B,,CMD)
//SYSUT1   DD *
!JOB IBMWARN,MANAGER.SYS;HIPRI;OUTCLASS=LP,1
!TELLOP ; #### IBM IS GOING DOWN IN 10 MINUTES
!TELLOP ; #### SIGNOFF MRJE AND NRJE NOW
!EOJ
/*
//