List Objects Secured by Authorization List (QSYLATLO) API

Required Parameter Group:

Qualified user space name

Input

Char(20)

Format name

Input

Char(8)

Authorization list

Input

Char(10)

Error code

I/O

Char(*)

Optional Parameter Group 1:

Stream file path name

Input

Char(*)

Length of stream file path name

Input

Binary(4)

Default Public Authority: *USE

Threadsafe: Yes

The List Objects Secured by Authorization List (QSYLATLO) API puts a list of objects secured by an authorization list into a user space or stream file.

A user space can only hold 16 megabytes of data, so if this API needs to return more data than the user space can hold, it will be necessary to specify a stream file. The data placed in the stream file may be quite large. Currently this API can handle returning approximately two gigabytes of data in a stream file.

An estimate of how many entries a user space can hold can be calculated by doing the following:

Determine how much space is available for entries by subtracting the size of the header sections from 16 megabytes. The header sections include the Generic Header, Input Parameter Section, and the Header Section.
```
space available for entries = 16 megabytes - size of Generic Header -
                              size of Input Parameter Section - size of Header Section
```
Add the length of the fixed portion of the format to the estimated size of a path name (if the format supports path names) and divide this into the amount of space available for the entries.
```
num entries = space available for entries / (length of fixed portion + estimated size of
                                             path name)
```

For example, do the following to determine the approximate number of format ATLO0400 entries a user space can hold.

Determine how much space is available for entries by subtracting the size of the header sections from 16 megabytes. We will allow an estimated 500 bytes for the pathname stored in the Input Parameter Section.
```
16,776,392 = 16,777,216 - 192 - (48 + 500) - 84
```
Add the length of the fixed portion of format ATLO0400, 220 bytes, to the estimated size of a path name, 500 bytes. Then divide this value, 720 bytes, into the space available for entries. This results in approximately 23300 format ATLO0400 entries.
```
23300 = 16,776,392 / (220 + 500)
```

This API provides information similar to the Display Authorization List Objects (DSPAUTLOBJ) command.

The QSYS2.AUTHORIZATION_LIST_INFO view can be used as an alternative to this API. See AUTHORIZATION_LIST_INFO view for more information.

Authorities and Locks

User Space Authority: *CHANGE
Authority to Library Containing User Space: *EXECUTE
Stream File Authority: *W (if an existing stream file is specified); *WX (to the parent directory if the specified stream file does not exist and is to be created)
Note: If a stream file path name is specified, *X authority is required for each directory in the path. Adopted authority is not used to access the stream file.
Authorization List Authority: Must not be *EXCLUDE authority or must be authorized to the Database Security Administrator function of the IBM i through System i™ Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_DB_SECADM, can also be used to change the list of users allowed to use the function.

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The name of the existing user space where the list of objects secured by the authorization list is returned to. The first 10 characters specify the user space name, and the second 10 characters specify the library.

I f you want to use a stream file instead of a user space, then use this special value for the user space name:

*STMF

Use the optional parameters, Stream file path name and Length of stream file path name, to specify the stream file path name. When this special value is specified, the library name must be blanks.

You can use these special values for the library name:

*CURLIB

The current library is used to locate the user space. If there is no current library, QGPL (general purpose library)

*LIBL

The library list is used to locate the user space.

Format name

INPUT; CHAR(8)

The name of the format used to list objects secured by the authorization list.

You can specify these formats:

ATLO0100

Each entry contains the object name, library, type, authority holder indicator, auxiliary storage pool (ASP) device name of library, and ASP device name of object.

ATLO0110

This format only returns path names for objects in a directory. Each entry contains the offset to the path name, the length of the path name, type, authority holder indicator, ASP device name of object, and the path name value. Objects in the QSYS.LIB and QDLS file systems are not returned with this format.

ATLO0200

Each entry contains the same information as ATLO0100 plus the object owner, attribute, text, and primary group.

ATLO0210

This format only returns path names for objects in a directory. Each entry contains the same information as format ATLO0110 plus the object owner, attribute, text, and primary group. Objects in the QSYS.LIB and QDLS file systems are not returned with this format.

ATLO0300

Each entry contains the length of the entry, object name, library, type, authority holder indicator, document library object (DLO) name, the name of the folder that the DLO is in, the displacement to the path name, the length of the path name, ASP device name of library, ASP device name of object, and the path name value. Objects in all file systems are returned with this format. Objects are returned consecutively in three groups. Objects in the QSYS.LIB file system are in one group, objects in the QDLS file system are in another group, and objects in directories are in the other group. Information returned in the Header Section indicates how to get to the beginning of each group of objects.

ATLO0400

Each entry contains the same information as ATLO0300 plus the object owner, primary group, attribute, and text. Objects in all file systems are returned with this format. Objects are returned consecutively in three groups. Objects in the QSYS.LIB file system are in one group, objects in the QDLS file system are in another group, and objects in directories are in the other group. Information returned in the Header Section indicates how to get to the beginning of each group of objects.

Authorization list

INPUT; CHAR(10)

The name of the authorization list for which the secured objects are returned.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group 1

Stream file path name

INPUT; CHAR(*)

The stream file name, specified as a path name. This parameter is assumed to be represented in the coded character set identifier (CCSID) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

If the stream file does not exist, it will be created. The user currently running this API will be the owner and the public authority will be *EXCLUDE.

If the length of the stream file path name is -1, then this parameter is assumed to be a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name. For more information on the Qlg_Path_Name_T structure, see Path name format.

If the length of stream file path name is 0, then this parameter is not used.

Length of stream file path name

INPUT; BINARY(4)

The length of the stream file path name in bytes. If the length is -1, the stream file path name parameter is assumed to be a Qlg_Path_name_T structure. This value must be zero if no stream file path name is specified.

User Space or Stream File Variables

The following tables describe the order and format of the data returned. For detailed descriptions of the fields in the tables, see Field Descriptions. When you retrieve list entry information for formats ATLO0100, ATLO0200, ATLO0300, or ATLO0400 you must use the entry size returned in the generic header to access list entries as the size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. When you retrieve list entry information for formats ATLO0110 and ATLO0210 you must use the offset to path name of the current entry + the length of path name of the current entry to access the next entry.

Input Parameter Section

Offset

Type

Field

Dec

Hex

CHAR(10)

User space name specified

CHAR(10)

User space library name specified

CHAR(8)

Format name

CHAR(10)

Authorization list

CHAR(2)

Reserved

BINARY(4)

Offset to stream file path name

BINARY(4)

Length of stream file path name

CHAR(*)

Stream file path name

Header Section

Offset

Type

Field

Dec

Hex

CHAR(10)

Authorization list

CHAR(10)

Authorization list library name

CHAR(10)

Owner

CHAR(10)

Primary group

BINARY(4)

Reason code

BINARY(4)

Offset to first QSYS.LIB object

BINARY(4)

Entry number of first QSYS.LIB object

BINARY(4)

Number of QSYS.LIB objects

BINARY(4)

Offset to first QDLS object

BINARY(4)

Entry number of first QDLS object

BINARY(4)

Number of QDLS objects

BINARY(4)

Offset to first directory object

BINARY(4)

Entry number of first directory object

BINARY(4)

Number of directory objects

BINARY(4)

CCSID of stream file path name in Input Parameter Section

ATLO0100 Format

Offset

Type

Field

Dec

Hex

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(10)

ASP device name of library

CHAR(10)

ASP device name of object

ATLO0110 Format

Offset

Type

Field

Dec

Hex

BINARY(4)

Offset to path name

BINARY(4)

Length of path name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(1)

Reserved

CHAR(10)

ASP device name of object

CHAR(*)

Path name

ATLO0200 Format

Offset

Type

Field

Dec

Hex

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(10)

Owner

CHAR(10)

Attribute

CHAR(50)

Text description

101

CHAR(10)

Primary group

111

CHAR(10)

ASP device name of library

121

CHAR(10)

ASP device name of object

ATLO0210 Format

Offset

Type

Field

Dec

Hex

BINARY(4)

Offset to path name

BINARY(4)

Length of path name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(10)

Owner

CHAR(10)

Attribute

CHAR(50)

Text description

CHAR(10)

Primary group

CHAR(1)

Reserved

100

CHAR(10)

ASP device name of object

CHAR(*)

Path name

ATLO0300 Format

Offset

Type

Field

Dec

Hex

BINARY(4)

Length of entry

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(12)

DLO name

CHAR(63)

Folder name

110

CHAR(2)

Reserved

112

BINARY(4)

Displacement to path name

116

BINARY(4)

Length of path name

120

CHAR(10)

ASP device name of library

130

CHAR(10)

ASP device name of object

CHAR(*)

Path name

ATLO0400 Format

Offset

Type

Field

Dec

Hex

BINARY(4)

Length of entry

CHAR(10)

Object name

CHAR(10)

Library name

CHAR(10)

Object type

CHAR(1)

Authority holder

CHAR(12)

DLO name

CHAR(63)

Folder name

110

CHAR(2)

Reserved

112

BINARY(4)

Displacement to path name

116

BINARY(4)

Length of path name

120

CHAR(10)

Owner

130

CHAR(10)

Attribute

140

CHAR(50)

Text description

190

CHAR(10)

Primary group

200

CHAR(10)

ASP device name of library

210

CHAR(10)

ASP device name of object

CHAR(*)

Path name

Field Descriptions

ASP device name of library. The auxiliary storage pool (ASP) device name where the object's library is stored. If the object's library is in the system ASP or one of the basic user ASPs, this field contains *SYSBAS.

ASP device name of object. The auxiliary storage pool (ASP) device name where the object is stored. If the object is in the system ASP or one of the basic user ASPs, this field contains *SYSBAS.

Attribute. The attribute of the secured object. If the object is not in the QSYS.LIB or QDLS file system, this field is blank.

Authority holder. Whether the object is an authority holder. If the object is an authority holder, this field is Y. If not, this field is N.

Authorization list. The name of the authorization list for which the list of objects is returned.

Authorization list library name. The name of the library containing the authorization list.

CCSID of path name in input parameter section. The CCSID value that is associated with the stream file path name in the Input Parameter Section. This value will be 0 if a stream file path name was not specified as input or if a Qlg_Path_Name_T structure was specified as the stream file path name.

Displacement to path name. The displacement in the entry to the start of the path name.

DLO name. The document library object (DLO) name for the object. If the object is not an *DOC (document) or *FLR (folder) object, this field is blank.

Entry number of first directory object. The entry number of the first directory object (objects not in the QSYS.LIB or QDLS file system) that is returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If the number of directory objects field is 0, this value is also 0.

Entry number of first QDLS object. The entry number of the first QDLS object that is returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If the number of QDLS objects field is 0, this value is also 0.

Entry number of first QSYS.LIB object. The entry number of the first QSYS.LIB object that is returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If the number of QSYS.LIB objects field is 0, this value is also 0.

Folder name. The name of the folder that contains the DLO object. If the object is not in a folder, this field contains *NONE.

Format name. The name of the format that is used to list objects secured by the authorization list.

Length of entry. The length (in bytes) of the current entry.

Length of path name. The length (in bytes) of the path name.

Length of stream file path name. The length (in bytes) of the stream file path name. If this length is -1, the stream file path name parameter is a Qlg_Path_name_T structure. If this value is zero, no stream file path name was specified.

Library name. The name of the library that contains the user space, object, or authorization list.

Number of directory objects. The number of objects in directories (objects not in the QSYS.LIB or QDLS file system) that are returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If there are no entries for objects in directories, 0 is returned.

Number of QDLS objects. The number of objects in the QDLS file system that were returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If there are no entries for QDLS objects, 0 is returned.

Number of QSYS.LIB objects. The number of objects in the QSYS.LIB file system that were returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If there are no entries for QSYS.LIB objects, 0 is returned.

Object name. The name of the object secured by the authorization list. If the object is not in the QSYS.LIB or QDLS file system, this field is blank.

Object type. The type of secured object.

Offset to first directory object. The offset to the first directory object (objects not in the QSYS.LIB or QDLS file systems) that was returned. This value is only set if using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If 'Number of directory objects' is 0, this value will also be 0.

Offset to first QDLS object. The offset to the first QDLS object that is returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If the number of QDLS objects field is 0, this value is also 0.

Offset to first QSYS.LIB object. The offset to the first QSYS.LIB object that is returned. This value is only set if you are using format ATLO0300 or ATLO0400. Otherwise, -1 is returned. If the number of QSYS.LIB objects field is 0, this value is also 0.

Offset to path name. The offset to the start of the path name.

Offset to stream file path name. The offset to the start of the stream file path name.

Owner. The name of the owner of the authorization list or object.

Path name. The path name of the object secured by the authorization list. The user must request a format that supports path names if path names are to be included in the information returned.

The structure of the path name returned is:

Description

Type

CCSID of the returned path name

Binary(4)

Country or region ID

Char(2)

Language ID

Char(3)

Reserved field

Char(3)

Flag byte

Binary(4)

Number of bytes in the path name

Binary(4)

Path delimiter

Char(2)

Reserved field

Char(10)

Path name value

Char(*)

Primary group. The name of the user who is the primary group for the authorization list or object. If there is no primary group for the authorization list or object, this field will contain a value of *NONE.

Reason code. The reason code that further describes why the list is only a subset of all objects. The following values can be returned:

Reason code 0000. The list returned contains all objects meeting the search criteria.
Reason code 0001. Objects were found that meet the search criteria but could not be included in the returned list. The requested format could not handle path names for directory objects.
Reason code 0002. Objects were found that meet the search criteria but could not be included in the returned list. The requested format could not handle objects found in library QSYS.
Reason code 0003. Directory objects were found but did not have links to them.

Reserved. This field is not used.

Stream file path name. The stream file path name used to return the list of objects secured by the authorization list. If the Length of stream file path name is greater then zero (not a Qlg_Path_name_T structure) then the CCSID this path name is represented in is returned in the Header Section in field CCSID of stream file path name in Input Parameter Section.

Text description. The descriptive text for the secured object. If the object is not in the QSYS.LIB or QDLS file system, this field is blank.

User space library name specified. The name of the library containing the user space or object.

User space name specified. The user space used to return the list of objects secured by the authorization list.

Error Messages

Message ID

Error Message Text

CPF22AF E

Not authorized to authorization list &1.

CPF2283 E

Authorization list &1 does not exist.

CPF2289 E

Unable to allocate authorization list &1.

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.

CPF3C3A E

Value for parameter &2 for API &1 not valid.

CPF3C36 E

Number of parameters, &1, entered for this API was not valid.

CPF3C90 E

Literal value cannot be changed.

CPF4ABC E

Internal error detected reason code &1.

CPF4AA9 E

Error occurred during processing of stream file.

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.

CPF9807 E

One or more libraries in library list deleted.

CPF9808 E

Cannot allocate one or more libraries on library list.

CPF9810 E

Library &1 not found.

CPF9820 E

Not authorized to use library &1.

CPF9830 E

Cannot assign library &1.

CPF9838 E

User profile storage limit exceeded.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2

[ Back to top | Security APIs | APIs by category ]