List Signed-On Users (QEZLSGNU) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | User name | Input | Char(10) |
| 4 | Display station name | Input | Char(10) |
| 5 | Include disconnected jobs and suspended group jobs |
Input | Char(10) |
| 6 | Include signed-off users with output waiting to print | Input | Char(10) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The List Signed-On Users (QEZLSGNU) API generates a list of signed-on users and places the list in the specified user space. The generated list replaces any existing lists in the user space.
When you specify a generic user name or a generic display station name, you can generate a subset of the signed-on user list. If both a user name and a display station name are specified, only entries that match both the user name and the display station name are included in the list of signed-on users.
You can use the QEZLSGNU API to get a list of users similar to that seen by using the Work with User Jobs (WRKUSRJOB) command with options STATUS (*ACTIVE) and JOBTYPE (*INTERACT).
Authorities and Locks
- User Space Authority
- *CHANGE
- Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The library list
- Format name
- INPUT; CHAR(8)
The content and format of the information returned for each member. The possible format names are:
SGNU0100 This format returns information about the user's job and what kind of activity they are performing. SGNU0200 This format returns the same information as the SGNU0100 format, plus the text descriptions of the user profile and display station. This format requires more processing than the SGNU0100 format. For more information, see SGNU0100 Format or SGNU0200 Format.
- User name
- INPUT; CHAR(10)
A specific user name, a generic user name, or the following special value:
*ALL All signed-on users
- Display station name
- INPUT; CHAR(10)
A specific display station name, a generic display station name, or the following special value:
*ALL All display stations with signed-on users
- Include disconnected jobs and suspended group jobs
- INPUT; CHAR(10)
An indicator for whether or not to include disconnected jobs and suspended group jobs. You must use one of the following special values:
*YES Include signed-on users with disconnected jobs and users whose group jobs have been suspended. *NO Do not include signed-on users with disconnected jobs and users whose group jobs have been suspended.
- Include signed-off users with output waiting to print
- INPUT; CHAR(10)
An indicator for whether or not to include signed-off users with output waiting to print. This would include all interactive signed-off users with output waiting to print and all batch graphical user interface jobs that have ended with output waiting to print.
You must use one of the following special values:
*YES Include signed-off users with output waiting to print. *NO Do not include signed-off users with output waiting to print.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of the Generated Lists
The signed-on user list consists of:
- A user area
- A generic header
- An input parameter section
- A list data section:
- SGNU0100 format
- SGNU0200 format
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result might not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name |
| 10 | A | CHAR(10) | User space library name |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | User name specified |
| 38 | 26 | CHAR(10) | Display station specified |
| 48 | 30 | CHAR(10) | Include disconnected jobs and suspended group jobs indicator specified |
| 58 | 3A | CHAR(10) | Include signed-off users with output waiting to print indicator specified |
SGNU0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Display station name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(10) | Activity |
| 36 | 24 | CHAR(10) | Activity name |
| 46 | 2E | CHAR(1) | Disconnect job allowed indicator |
| 47 | 2F | CHAR(17) | Reserved |
SGNU0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Everything from the SGNU0100 format | |
| 64 | 40 | CHAR(50) | Display station description |
| 114 | 72 | CHAR(50) | User description |
Field Descriptions
Activity. Information about what is happening with the interactive job. Common values for an interactive job are:
| blank | An activity is not currently set for this job. The activity might have been cleared with the Change Current Job (QWCCCJOB) API. |
| *BLDIDX | The user is using a file that is currently being rebuilt. The user's interactive job will be delayed until the file rebuild operation is complete or the Transfer to Secondary Job (TFRSECJOB) command has been run. The file name is in the activity name field. |
| *CMD | The user is running a command. The command name is in the activity name field. |
| *CMDENT | The user is currently on the Command Entry display. |
| *DLY | The Delay Job (DLYJOB) command has been run, and the user's interactive job will be delayed until the time limit specified has passed. |
| *DSCJOB | The user is temporarily signed-off (disconnected) the system (for example, option 80 on the ASSIST menu). |
| *DUMP | The user encountered an unexpected error, and a printout of diagnostic information (dump) is being created. |
| *GRP | The job is a suspended group job. The group name is in the activity name field. |
| *HLD | The user's interactive job is temporarily stopped and cannot run until it is released. |
| *MNU | The user is using a menu. The menu name is in the activity name field. |
| *MSG | The user is waiting for a reply to a message. |
| *PGM | The user is running a program. The program name is in the activity name field. |
| *PRT | The job has ended but has output waiting to print. |
| *SIGNOFF | A job is ending because the user has signed off
the system, or the interactive job has ended due to one of the following:
|
| *SYSRQS | The user has pressed the System Request key. |
| *S36PRC | The user is running a System/36™ environment procedure. The procedure name is in the activity name field. |
| *USR | The user is running a user-specified function. The function name is in the activity name field. |
Activity name. The name of the program, menu, command, user function, System/36 procedure, or file being used; or the group name of a suspended group job. The field is used only when the activity field is *BLDIDX, *CMD, *GRP, *MNU, *PGM, *S36PRC, or *USR. This field is blank for other activities.
Disconnect job allowed indicator. An indicator as to whether the job is allowed to be disconnected or not using the Disconnect Job (DSCJOB) command. The valid values that will be returned are:
| 1 | The job is allowed to be disconnected. |
| 0 | The job is not allowed to be disconnected. |
Display station description. The text that describes the device description of the display station to which the user is signed on.
Display station name. The name of the display station to which the user is currently signed on. This field is used as part of the job name by the system.
Display station specified. The display station or special value specified in the call to this API.
Format name. The name of the format that determines the content of the information returned for each signed-on user. This is specified on the call to this API.
Include disconnected jobs and suspended group jobs indicator specified. The include disconnected jobs and suspended group jobs indicator specified in the call to this API.
Include signed-off users with output waiting to print indicator specified. The include signed-off users with output waiting to print indicator specified in the call to this API.
Job number. The system-assigned job number.
Reserved. An ignored field.
User description. The text of the user profile description for the user currently signed on the system.
User name. The user profile name of the user currently signed on the system.
User name specified. The user name or special value specified in the call to this API.
User space library name. The library in which the user space is located.
User space name. The name of the user space that is to receive the generated list and the name of the library that contains this user space. This is specified in the call to this API.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1EA1 E | User name parameter is not valid. |
| CPF1EA2 E | Display station parameter is not valid. |
| CPF1EA3 E | Include disconnected jobs parameter is not valid. |
| CPF1EA4 E | Include signed-off users with output parameter not valid. |
| CPF1E99 E | Unexpected error occurred. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF811A E | User space &4 in &9 damaged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Operational Assistant APIs | APIs by category ]