IAZXJSAB — Obtain information about a currently running job

Description

Use the CREATE function with TYPE=SUBTASK to set or request job scheduler information for the current task. When an application is doing work on behalf of another work unit, the CREATE or UPDATE request identifies the work unit for whom the work is being done. IAZXJSAB provides the following services:

Create a JSAB.
Read from a JSAB.
Update a JSAB.
Delete a JSAB.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	CREATE, DELETE and UPDATE: APF authorization, supervisor state or system key READ: Problem or supervisor state and any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	If the caller specifies the ASCB parameter, any PASN, any HASN, any SASN; otherwise, PASN=HASN is required.
AMODE:	31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	None

Programming requirements

Include these mapping macros in your program: IAZJSAB, IHAASCB and IHAASSB. If you do not code the ASCB parameter, also include these additional mapping macros: IHAPSA, IKJTCB, and IHASTCB.

If you need more information about:

Mapping macro:	Look in:	Under the name:
IAZJSAB	z/OS MVS Data Areas in the z/OS Internet library	JSAB
IHAASCB	z/OS MVS Data Areas in the z/OS Internet library	ASCB
IHAASSB	z/OS MVS Data Areas in the z/OS Internet library	ASSB
IHAPSA	z/OS MVS Data Areas in the z/OS Internet library	PSA
IHASTCB	z/OS MVS Data Areas in the z/OS Internet library	STCB
IKJTCB	z/OS MVS Data Areas in the z/OS Internet library	TCB

Restrictions

The following restrictions apply:

You must not create an address space JSAB.
You may only update or delete a JSAB that you have created.

Input register information

Before issuing the IAZXJSAB macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The IAZXJSAB macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IAZXJSAB macro.

IAZXJSAB

␢	One or more blanks must follow IAZXJSAB macro.

CREATE READ UPDATE DELETE

,TYPE=SUBTASK
	Default: ADDRSP (Restricted use)

,ASCB=`ascb addr`	`ascb addr`: RX-type address or register (2) - (12).
	Default: The address of the ASCB for the caller's home address space.

,COMPID=`compid addr`	`compid addr`: RS-type address or register (2) - (12).

,CODELEV=`codelev addr`	`codelev addr`: RX-type address or register (2) - (12).


,WORKID=`workid addr`	`workid addr`: RS-type address or register (2) - (12).

,JOBID=`jobid addr`	`jobid addr`: RS-type address or register (2) - (12).

,JOBNAME=`jobname addr`	`jobname addr`: RS-type address or register (2) - (12).

,PREFIX=`prefix addr`	`prefix addr`: RS-type address or register (2) - (12).

,USERID=`userid addr`	`userid addr`: RS-type address or register (2) - (12).

,EXECST=`execst addr`	`execst addr`: RS-type address or register (2) - (12).

,XCFGPNM=`xcfgpnm addr`	`xcfgpnm addr`: RS-type address or register (2) - (12).

,JESTAT=`jestat addr`	`jestat addr`: RS-type address or register (2) - (12).

,JSABLVL=`jsablvl addr`	`jsablvl addr`: RS-type address or register (2) - (12).

,JOBCORR=`jobcorr addr`	`jobcorr addr`: RS-type address or register (2) - (12).

Parameters

The parameters are explained as follows:

CREATE | READ | UPDATE | DELETE

Requests the type of IAZXJSAB function.

,TYPE=SUBTASK

Specifies the type of JSAB to be created or deleted. TYPE is valid only for the CREATE and DELETE services. You must code TYPE=SUBTASK, as the default is TYPE=ADDRSP.

,ASCB=ascb addr

Specifies the address of an address space control block (ASCB).

ASCB is valid only for the READ and DELETE services. The default value is the address of the ASCB that represents the caller's home address space.

,COMPID=compid addr

With the CREATE service, COMPID specifies the location of the 4-character name of the subsystem that is creating the JSAB. With the READ service, COMPID specifies the location where the system is to return the 4-character name of the subsystem that created the JSAB. If JES2 or JES3 created the JSAB, the identifier is the common name of the JES (such as JES2 or JES3) and not the name of the JES2 or JES3 address space. If APPC/MVS created the JSAB, the identifier is ASCH.

COMPID is required for the CREATE service and is optional for the READ service. COMPID is not valid on the UPDATE and DELETE services.

,CODELEV=codelev addr

Specifies the code level of the creating component. Valid values are 0-255.

CODELEV is required for the CREATE service and is optional for the READ service. CODELEV is not valid on the UPDATE and DELETE services.

,WORKID=workid addr

Specifies the location where the system is to return the 8-character work unit identifier. The system returns identical information for the work unit ID and job ID.

WORKID is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,JOBID=jobid addr

Specifies the location where the system is to return the 8-character job identifier. The system returns identical information for the work unit ID and job ID.

JOBID is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,JOBNAME=jobname addr

Specifies the location where the system is to return the 8-character job name.

JOBNAME is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,PREFIX=prefix addr

Specifies the location where the system is to return the 8-character message prefix. In a JES2 system, the prefix is the job ID. In a JES3 system, the prefix is the job name.

PREFIX is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,USERID=userid addr

Specifies the location where the system is to return the 8-character user ID.

USERID is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,EXECST=execst addr

Specifies the location where the system is to return the 8-byte execution start time, in time-of-day (TOD) clock format.

EXECST is not valid on the DELETE service.

,XCFGPNM=xcfgpnm addr

Specifies the location where the system is to return the 8-character XCF group name of the subsystem that created the JSAB. The XCF group name is available only if JES2 created the JSAB.

XCFGPNM is not valid on the DELETE service and is optional on the CREATE, READ, and UPDATE services.

,JESTAT=jestat addr

Specifies the location where the system is to return the 8-byte JES status for the address space.

For the meaning of values that can be returned to the specified address, see the field JSABJSTA in the mapping macro IAZJSAB in z/OS MVS Data Areas in the z/OS Internet library.

JES status only applies on the job level. Therefore, using the JESTAT keyword forces the access to the address space level JSAB. JESTAT is not compatible with TYPE(SUBTASK). For READ and UPDATE, JESTAT can only be used with the JOBCORR keyword—JESTAT cannot be used together with any other job attribute.

,JSABLVL=jsablvl addr

Specifies the location where the system is to return the 1-byte level of the JSAB to be used for the READ request. If the value returned is 4, it indicates a subtask level JSAB.

JSABLVL is valid only on the READ service.

,JOBCORR=jobcorr addr

Specifies the location where the system is to return the 64-character job correlator field. Because JOBCORR only applies on the job level, using the JOBCORR keyword forces the access to the address space level JSAB. JOBCORR is not compatible with TYPE(SUBTASK). For READ and UPDATE, JOBCORR can only be used with the JESTAT keyword—JOBCORR cannot be used with any other job attribute.

JOBCORR is optional for CREATE, READ and UPDATE. JOBCORR is not valid for DELETE.

ABEND codes

None.

Return codes

When IAZXJSAB macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes.

Table 1. Return and Reason Codes for the IAZXJSAB Macro
Return Code	Meaning and Action
0	Meaning: Processing completed successfully. Action: None.
4	Meaning: Storage was not obtained or released for the JSAB. (CREATE and DELETE only.) Action: None.
8	Meaning: The JSAB was not found. No information was returned. Action: None required; however, you might want to make sure the specified ASCB address is correct.
12	Meaning: The requested field does not exist in the active JSAB. Action: None.

Example

Obtain the job ID of the current address space.

         IAZXJSAB READ,JOBID=MYJOBID
          .
          .
          .
MYJOBID  DS    CL8