Parameter list for access control authorization routines

The parameter list of access control authorization routines contains pointers to other information, such as the work area and the authorization ID list.

Begin program-specific programming interface information.

The following diagram shows how the parameter list points to other information.

Begin figure description. The authorization routine's parameter list points to other information. End figure description. — Figure 1. How an authorization routine's parameter list points to other information

The work area (4096 bytes) is obtained once during the startup of Db2 and only released when Db2 is shut down. The work area is shared by all invocations to the exit routine.

At invocation, registers are set, and the authorization checking routine uses the standard exit parameter list (EXPL). The following is a list of the exit-specific parameters, described by macro DSNDXAPL. Field names indicated by an asterisk (^*) apply to initialization, termination, and authorization checking. Field names indicated by double asterisks (^**) apply to initialization only. Other fields apply to authorization checking only.

Table 1. Parameter list for access control authorization routines
Name	Hex offset	Data type	Input or output	Description
XAPLCBID^*	0	Character, 2 bytes	Input	Control block identifier; value X'216A'.
XAPLLEN ^*	2	Signed, 2-byte integer	Input	Length of XAPL; value X'100' (decimal 256).
XAPLEYE ^*	4	Character, 4 bytes	Input	Control block eye catcher; value XAPL.
XAPLLVL ^*	8	Character, 8 bytes	Input	Db2 version and level; for example, VxRxMx .
XAPLSTCK ^*	10	Character, 8 bytes	Input	The store clock value when the exit is invoked. Use this to correlate information to this specific invocation.
XAPLSTKN ^*	18	Character, 8 bytes	Input	STOKEN of the address space in which XAPLACEE resides. Binary zeroes indicate that XAPLACEE is in the home address space.
XAPLACEE ^*	20	Address, 4 bytes	Input	ACEE address Of the Db2 address space (ssnmDBM1) when XAPLFUNC is 1 or 3. Of the primary authorization ID associated with this agent or XAPLUCHK ID when XAPLFUNC is 2. There might be cases where an ACEE address is not available for an agent. In such cases this field contains binary zeroes.
XAPLUPRM ^*	24	Character, 8 bytes	Input	One of the following IDs: When XAPLFUNC is 1 or 3, it contains the User ID of the Db2 address space (ssnmDBM1) When XAPLFUNC is 2, it contains the primary authorization ID associated with the agent. The primary authorization ID is set to XAPLUCHK ID when XAPLOWAC is on.
XAPLFUNC ^*	2C	Signed, 2-byte integer	Input	Function to be performed by exit routine: 1 Initialization 2 Authorization Check 3 Termination
XAPLGPAT ^*	2E	Character, 4 bytes	Input	Db2 group attachment name for data sharing. The Db2 subsystem name if not data sharing.
XAPLUCKT	32	Character, 1 byte	Input	Type of the authorization ID on which Db2 performs the check: ' ' An authorization ID L A role
XAPLONRT	33	Character, 1 byte	Input	Type of the authorization ID that owns the object in XAPLOWNR: ' ' An authorization ID L A role
XAPLSDEF	34	Character, 1 byte	Input	System-defined object: S A system-defined routine or package ' ' Not a system-defined object
XAPLRSV1	35	Character, 3 bytes		Reserved
XAPLPRIV	38	Signed, 2-byte integer	Input	Db2 privilege being checked. Security administrator (SECADM) authority and secure object creation (CREATE_SECURE_OBJECT) privilege required for row and column access control
XAPLTYPE	3A	Character, 1	Input	Db2 object type: B Buffer pool C Collection D Database E Distinct typeDistinct type F User-defined functionUser-defined function H Global variable J JAR K Package L Role M Schema N Trusted context O Stored procedure P Application plan Q Sequence R Table space S Storage group T Table U System privilege V View
XAPLFLG1	3B	Character, 1 byte	Input	The highest-order bit, bit 8, (XAPLCHKS) is on if the secondary IDs associated with this authorization ID (XAPLUCHK) are included in the Db2 authorization check. If it is off, only this authorization ID is checked. Bit 7 (XAPLUTB) is on if this is a table or view privilege (SELECT, INSERT, and so on) and if SYSCTRL, SQLADM, System DBADM, ACCESSCTRL, DATAACCESS, or SECADM is not sufficient authority to perform the specified operation on a table or view. SYSCTRL, SQLADM, System DBADM, ACCESSCTRL, DATAACCESS, or SECADM does not have the privilege of accessing user data unless the privilege is specifically granted to it. Bit 6 (XAPLAUTO) is on if this is an autobind. Bit 5 (XAPLCRVW) is on if the installation parameter DBADM CREATE AUTH is set to YES. Bit 4 (XAPLRDWR) is on if the privilege is a write privilege. If the privilege is a read-only privilege, bit 4 is off. Bit 3 (XAPLFSUP) is on to suppress error messages. These error messages are caused by intermediate checks that do not affect the final result. Bit 2 (XAPLRAOO) is on if this operation is in a trusted context that is defined with the ROLE AS OBJECT OWNER clause. Bit 1 (XAPLIMPD) is on if authorization checking involves an implicitly created database.
XAPLUCHK	3C	Address, 4 bytes	Input	Address to the authorization ID on which Db2 performs the check. It could be the primary, secondary, or some other ID. This is a VARCHAR(128) field.
XAPLOBJN	40	Address, 4 bytes	Input	Address to the unqualified name of the object with which the privilege is associated. This is a VARCHAR(128) field.It is one of the following names: Name Length Application plan 8 Buffer pool 8 Collection VARCHAR(128) Database 8 Distinct type VARCHAR(128) Variable name VARCHAR(128) JAR VARCHAR(128) Package VARCHAR(128) Role VARCHAR(128) Schema VARCHAR(128) Sequence VARCHAR(128) Storage group VARCHAR(128) Table VARCHAR(128) Table space 8 Trusted context VARCHAR(128) User-defined function VARCHAR(128) View VARCHAR(128) For special system privileges (SYSADM, SYSCTRL, and so on) this field might contain binary zeroes.
XAPLOWNQ	44	Address, 4 bytes	Input	Address of the object owner (creator) or object qualifier. The contents of this parameter depends on either the privilege being checked or the object. This is a VARCHAR(128) field. If this field is not applicable, it contains binary zeros.
XAPLREL1	48	Address, 4 bytes	Input	Address of other related information 1. The contents of this parameter depend on either the privilege being checked or the object. This is a VARCHAR(128) field. If this field is not applicable, it contains binary zeros.
XAPLREL2	4C	Address, 4 bytes	Input	Address of other related information 2. The contents of this parameter depends on the privilege being checked. This is a VARCHAR(128) field. If this field is not applicable, it contains binary zeros.
XAPLDBSP	50	Address, 4 bytes	Input	Address of database information. This information is passed for CREATE VIEW and CREATE ALIAS. If this field is not applicable, it contains binary zeros.
XAPLOWNR	54	Address, 4 bytes	Input	Address of the object owner. This is a VARCHAR(128) field. If this field is not applicable, it contains binary zeros.
XAPLROLE	58	Address, 4 bytes	Input	Address of the user's role when operating in a trusted context. If this field is not applicable, it contains binary zeros.
XAPLOONM	5C	Address, 4 bytes	Input	Address of other object name
XAPLOOON	60	Address, 4 bytes	Input	Address of other object owner
XAPLBSCM	64	Address, 4 bytes	Input	Address of base table qualifier of a view or repeated view qualifier
XAPLBNAM	68	Address, 4 bytes	Input	Address of base table name of a view or repeated view name
XAPLBCOL	6C	Address, 4 bytes	Input	Address of base table column name of a view or repeated view column name
XAPLCLST^**	70	Address, 4 bytes	Output	Address to the RACLISTed class list
XAPLCLNM^**	74	Signed, 2-byte integer	Output	Number of RACLISTed Db2 classes
XAPLFLG3^**	76	Character, 1 byte	Output	Bit 8 (the highest order bit) is on if classes are defined in multi-subsystem scope (XAPLMSSC) The remaining 7 bits are reserved.
XAPLRSV2	77	Character, 42 bytes		Reserved.
XAPLOOTP	A1	Character, 1 byte	Input	Other object type or the owner of the base table of a view
XAPLOOOT	A2	Character, 1 byte	Input	Other object owner type or the owner type of the base table of a view
XAPLRSV3	A3	Character, 1 byte		Reserved
XAPLXBTS	A4	Timestamp, 10 bytes	Input	The function resolution timestamp. Authorizations received prior to this timestamp are valid. Applicable to functions and procedures.
XAPLONWT	AE	Character, 1 byte	Output	Information required by Db2 from the exit routine for the UPDATE and REFERENCES table privileges: Value Explanation ' ' Requester has privilege on the entire table * Requester has privilege on just this column
XAPLFLG2	AF	Character, 1 byte	Input	Bit 8 (the highest-order bit) is on if an object is associated with the row and column access control (XAPLSOBJ) Bit 7 is on if the SEPARATE SECURITY system parameter is set to YES (XAPLSPSC) Bit 6 is on when a catalog table (XAPLSCTB) can be accessed only by the SECADM authority. Bit 5 (XAPLACAC) is on when authorization checking is done for statements that involve the package authorization, routine authorization, or dynamic statement cache. Bit 4 (XAPLOWAC) is on if ACEE FOR XAPLUCHK ID is set IN XAPLACEE Bit 3 is on if class names are defined in multi-subsystem scope (XAPLMSSC) The remaining 2 bits are reserved.
XAPLDIAG	B0	Character, 80 bytes	Output	Information returned by the exit routine to help diagnose problems.

The following table includes database information for determining authorization for creating a view. The address to this parameter list is in XAPLREL2.

Table 2. Parameter list for access control authorization routines—database information
Name	Hex offset	Data type	Input or output	Description
XAPLDBNP	0	Address	Input	Address of information for the next database. X'00000000' indicates no next database exists.
XAPLDBNM	4	Character, 8 bytes	Input	Database name.
XAPLDBDA	C	Character, 1 byte	Output	Required by Db2 from the exit routine for CREATE VIEW. A value of Y and EXPLRC1=0 indicate that the user ID in field XAPLUCHK has database administrator authority on the database in field XAPLDBNM. When the exit checks if XAPLUCHK can create a view for another authorization ID, it first checks for SYSADM or SYSCTRL authority. If the check is successful, no more checking is necessary because SYSCTRL authority (for non-user tables) or SYSADM authority satisfies the requirement that the view owner has the SELECT privilege for all tables and views that the view might be based on. This is indicated by a blank value and EXPLRC1=0. If the authorization ID does not have SYSADM or SYSCTRL authority, the exit checks if the view creator has DBADM on each database of the tables that the view is based on because the DBADM authority on the database of the base table satisfies the requirement that the view owner has the SELECT privilege for all base tables in that database.
XAPLDBIM	D	Character, 1 bytes	Input	A value of 'Y' indicates that the database is implicitly created.
XAPLRSV5	E	Character, 2 bytes	none	Reserved.

Table 3. Parameter list for access control authorization routines-class list array information
Name	Hex offset	Data type	Input or output	Description
XAPLCMEM^**	0	Character, 8 bytes	Output	Db2 class name

XAPLOWNQ, XAPLREL1 and XAPLREL2 might further qualify the object or may provide additional information that can be used in determining authorization for certain privileges. The following is a list of the privileges and the contents of XAPLOWNQ, XAPLREL1 and XAPLREL2.

Table 4. Related information for certain privileges
Privilege	Object type (XAPLTYPE)	XAPLOWNQ	XAPLREL1	XAPLREL2	XAPLOWNR
0263 (USAGE)	E	Address of schema name	Address of distinct type owner	Contains binary zeroes	Address of distinct type owner
0291 (READ) 0292 (WRITE)	H	Address of schema name	Address of global variable owner	Contains binary zeroes	Address of global variable owner
0064 (EXECUTE) 0265 (START) 0266 (STOP) 0267 (DISPLAY)	F	Address of schema name	Address of user-defined function owner	Contains binary zeroes	Address of user-defined function owner
0263 (USAGE)	J	Address of schema name	Address of JAR owner	Contains binary zeroes	Address of JAR owner
0064 (EXECUTE)	K	Address of collection ID	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0065 (BIND)	K	Address of collection ID	Address of package owner	Contains binary zeroes	Address of package owner
0073 (DROP)	K	Address of collection ID	Contains binary zeroes	Address of version ID	Contains binary zeroes
0097 (COMMENT)	K	Address of collection ID	Address of package owner	Contains binary zeroes	Address of package owner
0225 (COPY ON PKG)	K	Address of collection ID	Address of package owner	Contains binary zeroes	Address of package owner
0228 (ALLPKAUT)	K	Address of collection ID	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0229 (SUBPKAUT)	K	Address of collection ID	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0252 (ALTERIN) 0097 (COMMENT) 0252 (DROPIN)	M	Address of schema name	Address of object owner	Contains binary zeroes	Address of object owner
0064 (EXECUTE) 0265 (START) 0266 (STOP) 0267 (DISPLAY)	O	Address of schema name	Address of procedure owner	Contains binary zeroes	Address of procedure owner
0065 (BIND)	P	Address of plan owner	Contains binary zeroes	Contains binary zeroes	Address of plan owner
0097 (COMMENT)	P	Address of plan owner	Contains binary zeroes	Contains binary zeroes	Address of plan owner
0061 (ALTER) 0263 (USAGE)	Q	Address of schema name	Address of sequence name	Contains binary zeroes	Contains binary zeroes
0061 (ALTER)	R	Address of database name	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0073 (DROP)	R	Address of database name	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0087 (USE)	R	Address of database name	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0053 (UPDATE) 0054 (REFERENCES)	T	Address of table schema	Address of column name, if applicable	Address of database name	Address of table owner
0022 (CATMAINT CONVERT) 0050 (SELECT) 0051 (INSERT) 0052 (DELETE) 0055 (TRIGGER) 0056 (CREATE INDEX) 0061 (ALTER) 0073 (DROP) 0075 (LOAD) 0076 (CHANGE NAME QUALIFIER) 0097 (COMMENT) 0098 (LOCK) 0233 (ANY TABLE PRIVILEGE) 0251 (RENAME) 0275 (REFRESH)	T	Address of table schema	Contains binary zeroes	Address of database name	Address of table owner
0020 (DROP ALIAS) 0104 (DROP SYNONYM)	T	Address of table schema	Contains binary zeroes	Contains binary zeroes	Contains binary zeroes
0103 (ALTER INDEX) 0105 (DROP INDEX) 0274 (COMMENT ON INDEX) 0283 (RENAME INDEX)	T	Address of table schema	Contains binary zeroes	Address of database name	Address of index owner
0227 (BIND AGENT)	U	Address of package owner	Contains binary zeroes	Contains binary zeroes	Address of package owner
0015 (CREATE ALIAS)	U	Contains binary zeroes	Contains binary zeroes	Address of database name, if the alias is on a table	Contains binary zeroes
0053 (UPDATE)	V	Address of view schema	Address of column name, if applicable	Address of the database name of the view's base table, if applicable	Address of view owner
0051 (INSERT) 0052 (DELETE)	V	Address of view schema	Contains binary zeroes	Address of the database name of the view's base table, if applicable	Address of view owner
0050 (SELECT) 0073 (DROP) 0097 (COMMENT) 0233 (ANY TABLE PRIVILEGE)	V	Address of view schema	Contains binary zeroes	Contains binary zeroes	Address of view owner
0055 (TRIGGER)	V	Address of view schema	Contains binary zeroes	Contains binary zeroes	Address of view owner
0061 (ALTER)	V	Address of view schema	Contains binary zeroes	Contains binary zeroes	Address of view owner

The following is a list of data types and field lengths.

Table 5. Data types and field lengths
Resource name or other	Type	Length
Database name	Character	8
Global variable name	Character	VARCHAR(128)
Table name qualifier	Character	VARCHAR(128)
Object name qualifier	Character	VARCHAR(128)
Column name	Character	VARCHAR(128)
Collection ID	Character	VARCHAR(128)
Plan owner	Character	VARCHAR(128)
Package owner	Character	VARCHAR(128)
Package version ID	Character	VARCHAR(64)
Schema name	Character	VARCHAR(128)
Distinct typeowner	Character	VARCHAR(128)
JAR owner	Character	VARCHAR(128)
User-defined function owner	Character	VARCHAR(128)
Procedure owner	Character	VARCHAR(128)
View name qualifier	Character	VARCHAR(128)
Sequence owner	Character	VARCHAR(128)
Sequence name	Character	VARCHAR(128)

End program-specific programming interface information.