Text lookup service (IAZTLKUP)

For each job that matches specified filter requirements, an information element is added to the chain pointed to by STATJOBF. There are some fields defined in the sections of the job information element that can be further processed.

The STTRPHAZ field is reported within the Job Queue Element Terse Section, and contains a code that identifies the current phase of the job. Job phase codes are documented under the STATPHAZ field. Applications that display information retrieved using SSI 80 can display text to the end user. Rather than have applications interpret the job phase code, the text lookup service (IAZTLKUP) provides text that is equivalent to the code.

The IAZTLKUP text lookup service enables the user to supply extended status SSI 80 information to the service and retrieve a text description for specific fields. The service supports interpreting the job phase code and job delay reasons, which are reported in the Job Queue Element Execution Scheduling section (STATSCHD) flag bytes STSCAHLD and STSCAHL2. Refer to Job queue element sections. The application can perform an extended status SSI 80 call and then invoke the IAZTLKUP text lookup service to retrieve a text description for the job phase code or any job delay reasons for a given job information element.

IAZTLKUP also provides the capability of returning different levels of text for a given code. This provides the capability to report different amounts of detail and information for a given code or a given delay reason. The text lookup tables provide JES-specific text, and also a generalized text description: the macro invoker indicates which level of text to return. The IAZTLKUP macro documents the text levels that are supported by each text table.

Text lookup for flag bytes such as the job delay reasons work slightly differently that the simple lookup for a job phase code, because there can be multiple reasons for a job execution delay. The text lookup service return the text for the first job delay reason that is encountered, indicating to the macro invoker if there are more job delay reasons to interpret. You can invoke the IAZTLKUP text lookup service in a loop to receive all job delay reasons for a given job information element.

Text lookup (IAZTLKUP) macro

The interface to the text lookup service is the IAZTLKUP macro. The service requires a parameter list which is filled in by the expanded macro code. This parameter list is mapped by the IAZTLKDF macro. The IAZTLKUP text lookup service can interpret the following fields and return equivalent text information:

Job phase code (STTRPHAZ)
Job delay reasons (STSCAHLD and STSCAHL2)

IAZTLKUP syntax

The IAZTLKUP macro uses the following syntax:

IAZTLKUP TABLEID=tableid,
	LEVEL=level,
	SSOB=ssob,
	DATASTR=datastr,
	OUTAREA=outarea,
	OUTLEN=outlen,
	MOREFLG=moreflg,
	MF=(E,parmlist)

tableid

Specifies the 3 character ID of the type of lookup to perform. Supported types are:

PHZ: Job phase code lookup.
DLY: Job delay reasons lookup.

level

Indicates the level of text to be returned:

1: JES-specific text.
2: Generalized text description.
3: SDSF text description. Only supported by the PHZ table.

ssob

Specifies the address of the SSOB parameter list used in the Extended Status SSI 80 request to select the job information element being interpreted, which is supplied in the DATASTR parameter.

datastr

Specifies the address of the data structure containing the fields to be interpreted by the service. Extended Status SSI 80 can return data for numerous jobs, so the text lookup service requires the job information element to extract data from for the lookup. For a job phase code lookup, supply the address of a job information element (STATJQ), or the job queue element terse section (STATJQTR) within a job information element. For job delay reason lookup, supply STATJQ or the Job Queue Element Execution Scheduling section (STATSCHD) within a job information element. Refer to Job queue element sections.

outarea

Specifies the address of the storage location for the text lookup service to place the text derived from the lookup. If the size of the output area is smaller than the derived text, the text will be truncated. If the output area is larger than the derived text, the remaining bytes will be filled with blanks.

outlen

Specifies the length of the supplied output area for the derived text. If this parameter is not supplied, the service will use the length of OUTAREA.

moreflg

Specifies the address of the 4-byte storage location where remaining flag reason bits can be stored between IAZTLKUP macro invocations. This parameter is used for flag byte text lookup such as the job delay reasons. Set the MOREFLG location to 0 prior to the first invocation. After the first invocation, a return code of 4 indicates that more flag bits are available for interpretation. A return code of 0 indicates the last flag bit, if any, has been processed. If no flag bits are returned on the first invocation of IAZTLKUP, a return code of 0 and blanks in OUTAREA results.

If MOREFLG is not specified, the service only returns the first flag bit reason. If the service is invoked in a loop without MOREFLG specified, the result can be an infinite loop.

If MOREFLG is specified but not set to zero prior to the first IAZTLKUP macro invocation, the results are unpredictable.

MF

Indicator for macro execution:

L: Allocates storage for the TLKUP DSECT that is used as the input parameter list to the IAZTLKUP service. Allocates an additional 256 bytes to be used as a work area by the IAZTLKUP service. MF must be invoked once with this indicator to set aside storage for the parameter list.
E: Generates the call to the IAZTLKUP service. Requires the list form (L) to have been previously specified.
Parmlist: Label used to reference the input parameter list TLKUP that is passed to the IAZTLKUP service.

Input register information

The IAZTLKUP service requires a non-standard save area address in register 13. This save area must be 128 bytes to allow the IAZTLKUP service to save the 16 8-byte registers.

If the lookup being performed is a flag bit lookup (such as job delay reasons) including the MOREFLG parameter, MOREFLG must be set to zero before the first invocation of the IAZTLKUP service, or unpredictable results can occur.

Output register information

The IAZTLKUP service affects the registers in the following manner after exiting the macro:

Register: Content
R0/AR0: Destroyed. R0 is used as a work register.
R1/AR1: Destroyed. R1 is used as a work register.
R2-R13: Unchanged.
R14: Destroyed. Used as a return address.
R15/AR15: Destroyed. R15 contains a return code.

Return code information

The IAZTLKUP service supplies a return code in register 15 after exit. The following return codes are possible:

Return Code: Meaning and Results
0: The IAZTLKUP service was called successfully. For a flag bit lookup (such as job delay reasons), this indicates the last reason was interpreted. If no flag bit settings are found, OUTAREA contains blanks. If the code is not defined in the text lookup table, default text is returned in OUTAREA. For example, an unknown job phase code returns “UNKNOWN JOB PHASE”.
4: The IAZTLKUP service was called successfully for a flag bit interpretation (such as job delay reasons), and more flag bits remain to be interpreted.
8: No text value was returned. Check the parameter list field TLKRETCD for further information on the error.

Environment

Minimum Authorization: Problem or Supervisor state, with any PSW key

Dispatchable unit mode: Task

Cross Memory Mode: PASN=HASN=SASN

AMODE: 31 or 64 bit

ASC mode: Primary

Locks: none

Restrictions

None.

Text lookup service data definition (IAZTLKDF) macro

The Text Lookup Service data definition macro IAZTLKDF is used to map the input parameter list passed to the IAZTLKUP text lookup service. The TLKUP DSECT defines the service's input parameter list. The IAZTLKDF macro is invoked in the following manner:

IAZTLKDF DSECT=YES | NO

Input parameter list definition:

DSECT=YES: Generates a DSECT statement for the parameter list structure.
DSECT=NO: Does not generate a DSECT statement, and can be used to reserve storage for the parameter list in an existing DSECT.

IAZTLKDF parameter list return codes (TLKRETCD)

The following text lookup service data definition return codes are provided:

Name: Meaning
TLKRSUCC: Successful completion. For a flag lookup, no additional text is available.
TLKRLAST: Successful completion. For a flag lookup, additional text is available.
TLKRNOTF: Code/flag setting not found.
TLKRNTBL: No text table pointer in SSI output area.
TLKRBADS: Bad SSOB address, SSI function not supported, or bad SSI parameter list.
TLKRBADT: Bad text table ID.
TLKRNOUT: Output area address or length is zeroes.
TLKRBADE: Bad text table eyecatcher.
TLKRBADL: Bad text table level requested.
TLKRBADY: Bad text table type for request.

IAZTLKUP service input parameter list (TLKUP)

The TLKUP data structure is the input parameter list to the IAZTLKUP text lookup service. It is built by the code expanded by the expansion of the IAZTLKUP text lookup service macro. The parameter list fields are:

Field name: Description
TLKEYE: Eyecatcher.
TLKLEN: Length of TLKUP parameter list.
TLKTBLID: Text table ID used in the lookup.
TLKLEVEL: Level of text to lookup.
TLKSSOBP: Address of the SSOB.
TLKDATAP: Address of the SSI 80 output data where the code or flag to be interpreted is located (8 byte version).
TLKDATA4: Address of the SSI 80 output data where the code or flag to be interpreted is located (4 byte version).
TLKOUTP: Address of the output area where text is returned (8 byte version).
TLKOUT4: Address of the output area where text is returned (4 byte version).
TLKOUTL: Output area length.
TLKRETCD: Overall return code.

Length of text supplied

The text tables used by the IAZTLKUP text lookup service are defined within the JES at initialization time. The definitions supply the length of text that can be provided for each text level that is requested. Constants are declared in the Text Lookup Service data definition macro IAZTLKDF to identify the size of text that can be returned by the text lookup service. Current sizes are:

Table 1. Job phase text level
Job phase text level	IAZTLKDF constant name	Text size
Level 1	TPHZLEN1	64 characters
Level 2	TPHZLEN2	64 characters
Level 3	TPHZLEN3	20 characters

Table 2. Job phase text level
Job delay text level	IAZTLKDF constant name	Text size
Level 1	TDLYLEN1	20 characters
Level 2	TDLYLEN2	64 characters