Retrieve Library Description (RTVLIBD)

The Retrieve Library Description (RTVLIBD) command retrieves the description of a library and journaling information for the library. The values are returned (copied) to the specified variables in the program.

For parameters that are returned into CL variables by this command, the parameter descriptive title/and prompt text lists the minimum length for the CL variable. For character variables, a single number is shown. For decimal variables, two numbers are shown. The first number indicates the minimum variable length and the second number indicates the minimum number of decimal positions.

Restrictions:

1. You must have some authority other than *EXCLUDE authority for the library to retrieve the attributes of the library.
2. The actual default auditing value for objects created into the library is shown only if you have all object (*ALLOBJ) or audit (*AUDIT) special authority. If you do not have at least one of these special authorities, the default auditing value is shown as not available (*NOTAVL).

Parameters

Library (LIB)

Specifies the library for which attributes are to be retrieved. If a variable is specified, it must be 10 characters in length and contain a library name.

This is a required parameter.

name

Specify the name of the library for which attributes are to be retrieved.

CL var for TYPE (10) (TYPE)

Specifies a 10-character variable used to return the library type. The value PROD or the value TEST is returned.

CL var for ASP (2 0) (ASP)

Specifies a decimal (2 0) variable used to return the number of the auxiliary storage pool (ASP) from which the system allocates storage for the library. The following values can be returned:

1

The library is in the system auxiliary storage pool.

2-32

The library is in a user auxiliary storage pool.

-1

The library is in a primary or secondary auxiliary storage pool (ASP) with an ASP number larger than 32. The ASP device name for the primary or secondary ASP can be retrieved with the ASPDEV parameter.

CL var for ASPDEV (10) (ASPDEV)

Specifies a 10-character variable used to return the name of the auxiliary storage pool (ASP) device where storage is allocated for the library. One of the following special values can be returned:

*N

The name of the ASP device cannot be determined.

*SYSBAS

The library is in the system ASP (ASP 1) or in a basic user ASP (ASPs 2-32).

CL var for ASPGRP (10) (ASPGRP)

Specifies a 10-character variable used to return the name of the auxiliary storage pool (ASP) group where storage is allocated for the library. The ASP group name is the name of the primary ASP within the ASP group. One of the following special values can be returned:

*N

The name of the ASP device cannot be determined.

*SYSBAS

The library is in the system ASP (ASP 1) or in a basic user ASP (ASPs 2-32).

CL var for CRTAUT (10) (CRTAUT)

Specifies a 10-character variable used to return the create authority value of the library. The value *SYSVAL, *CHANGE, *ALL, *USE, or *EXCLUDE, or the name of an authorization list is returned.

CL var for CRTOBJAUD (10) (CRTOBJAUD)

Specifies a 10-character variable used to return the auditing value of the library. A value of *NOTAVL will be returned if you do not have either all object (*ALLOBJ) or audit (*AUDIT) special authority. The values that can be returned include *SYSVAL, *NONE, *USRPRF, *CHANGE, *ALL, and *NOTAVL. See the Create object auditing (CRTOBJAUD) parameter on the Create Library (CRTLIB) command for more information.

CL var for JRNSTS (1) (JRNSTS)

Specifies a 1-character variable used to return the current journaling status of the library. The value returned can be one of the following:

'0'

The library is not currently journaled.

'1'

The library is currently journaled.

Other journaling-related fields may contain data even though the library is not currently journaled. Refer to the Start Journal Library (STRJRNLIB) command for more information about journaling a library.

CL var for JRN (10) (JRN)

Specifies a 10-character variable used to return the name of the journal that receives the journaled changes to the library, if the library is currently journaled. If the library was previously journaled but is not currently journaled, this field shows the name of the last journal to which the library was journaled. This field is blank if journaling has never been started for this library.

CL var for JRNLIB (10) (JRNLIB)

Specifies a 10-character variable used to return the name of the library that contains the current or last journal that receives the journaled changes to the library, if the library is currently journaled. If the library was previously journaled but is not currently journaled, this field shows the name of the library that contains the last journal to which the library was journaled. This field is blank if journaling has never been started for this library.

CL var for JRNIMG (1) (JRNIMG)

Specifies a 1-character variable used to return the journal image information. The value returned can be one of the following:

' '

A blank if journaling has never been started for the library.

'0'

Only after images are deposited to the journal for changes to the library.

CL var for JRNOMTE (1) (JRNOMTE)

Specifies a 1-character variable used to return information regarding journal entries to be omitted. The value returned can be one of the following:

' '

A blank if journaling has never been started for the library.

'0'

No journal entries are omitted.

Journal entries cannot be omitted for libraries.

CL var for INHERIT (1) (INHERIT)

Specifies 1-character variable used to return information regarding whether or not new journal-eligible objects created into, moved into, or restored into the library should inherit journaling from the library according to the library's journal inherit rules. The journal inherit rules can be retrieved using the INHRULES parameter.

Note: You should examine the journal inherit rules to determine whether or not they are overridden by the existence of a data area with the name QDFTJRN in the library, regardless of the value of this field.

The value returned can be one of the following:

'0'

New journal-eligible objects do not inherit journaling from the library.

'1'

New journal-eligible objects inherit journaling from the library according to the journal inherit rules.

Refer to the Start Journal Library (STRJRNLIB) command for more information about journaling a library.

CL var for JRNSTRDATE (13) (JRNSTRDATE)

Specifies a 13-character variable used to return the date and time journaling was last started for the library. A value is returned in the form CYYMMDDHHMMSS where C = century; '0' indicates years 19xx and '1' indicates years 20xx; YY = year, MM = month, DD = day, HH = hour, MM = minutes and SS = seconds. This field is blank if journaling has never been started for the library.

CL var for STRJRNRCV (10) (STRJRNRCV)

Specifies a 10-character variable used to return the name of the oldest journal receiver needed to successfully use the Apply Journaled Changes (APYJRNCHG) command. This field is blank if either the library has never been journaled or it has not been saved and restored since journaling was started.

CL var for JRNRCVLIB (10) (JRNRCVLIB)

Specifies a 10-character variable used to return the name of the library that contains the starting journal receiver for apply. This field is blank if either the library has never been journaled or it has not been saved and restored since journaling was started.

CL var for RCVLIBASP (10) (RCVLIBASP)

Specifies a 10-character variable used to return the name of the auxiliary storage pool (ASP) device where storage is allocated for the library that contains the starting journal receiver for apply. This field is blank if either the library has never been journaled or it has never been saved and restored since journaling was started. The following special values can be returned:

*N

The name of the ASP device cannot be determined.

*SYSBAS

The library is in the system ASP (ASP 1) or in a basic user ASP (ASPs 2-32).

CL var for RCVLIBGRP (10) (RCVLIBGRP)

Specifies a 10-character variable used to return the name of the auxliliary storage pool (ASP) group where storage is allocated for the library that contains the starting journal receiver for apply. The ASP group name is the name of the primary ASP within the ASP group. The value returned may be the same as the value returned for the starting journal receiver library ASP device name field. This field is blank if either the library has never been journaled or it has not been saved and restored since journaling was started. The following special values can be returned:

*N

The name of the ASP device cannot be determined.

*SYSBAS

The library is in the system ASP (ASP 1) or in a basic user ASP (ASPs 2-32).

CL var for INHRULES (1280) (INHRULES)

Specifies a 1280-character variable used to return the information specified for the INHRULES keyword on the Start Journal Library (STRJRNLIB) command (or the Change Journal Object (CHGJRNOBJ) command) if journaling has ever been started for this library. If journaling has never been started for this library, the default journal inherit rules will be returned. The journal inherit rules specify which journal-eligible objects created into, moved into, or restored into the library should inherit journaling from the library. These rules only affect objects when they are created, moved into, or restored into the library. The journaling state and journaling attributes of objects within the library do not change if they are renamed. Once journaled, objects will not automatically end journaling if they are moved out of the library. Additionally, objects that are journaled prior to being moved into the library will not change their journaling state or attributes when they are moved.

The journal inherit rules are applied when both:

• the value returned for the INHERIT parameter is a '1', and
• the journal inherit rules overridden field (rulesOverridden) in the journal inherit rules below is a '0'.

Each rule defines the object types, object names, and operations that determine the objects to which the rule applies. Multiple rules can be defined for the same set of objects. If multiple rules are defined that would apply to the same object, the last rule defined for that object will be applied.

The fields are returned in the order described below. Note that some of the fields must be accessed using an offset or displacement field.

1. Version: A 4-byte unsigned integer field indicating the version of this structure. The value returned can be the following:

   1

   This is the first version of this structure.

   2

   This is the second version of this structure.

2. dispEntry: A 4-byte unsigned integer field containing the offset to the first journal inherit rule entry from the beginning of the journal inherit rules information.
3. lengthRules: A 4-byte unsigned integer field containing the total length of all journal inherit rules information.
4. numRules: A 4-byte unsigned integer field containing the number of journal inherit rule entries.
5. rulesOverridden: A 1-character field indicating whether or not the library's journal inherit rules will be overridden by a QDFTJRN data area that exists in the library. That is, the information in the QDFTJRN data area takes precedence over the journal inherit rules returned for the library. The value returned can be one of the following:

   '0'

   The QDFTJRN data area does not override the library's journal inherit rules.

   '1'

   The QDFTJRN data area overrides the library's journal inherit rules.

6. A 3-character reserved field containing hexadecimal zeros.
7. Inherit_Rules_Entry: The following structure repeats for the number of journal inherit rule entries. The displacement to the first journal inherit rule is returned in the dispEntry field above.
   1. nextEntryDisp: A 4-byte unsigned integer field containing the displacement to the next journal inherit rule entry from the beginning of this journal inherit rule entry.
   2. The layout of the next field(s) is dependent on the value returned in the Version field as follows:

      1

      a 20-character reserved field containing hexadecimal zeros.

      2

      the following fields are returned:

      1. namFltr: A 10-character field containing the name filter for the objects to which this rule applies if other criteria specified for this rule are satisfied. The value returned can be one of the following:

         *ALL

         This rule applies to all objects of the specified type regardless of the name of the object if other criteria specified for this rule are satisfied.

         name

         This rule applies to all objects with an object name that exactly matches the specified name if other criteria specified for this rule are satisfied.

         generic-name

         This rule applies to all objects with an object name that matches the generic name if other criteria specified for this rule are satisfied. A generic name is a character string that contains one or more characters (the prefix) followed by an asterisk (*). The object name will match the generic name if the object name has the same prefix as the generic object name.

      2. A 10-character reserved field containing hexadecimal zeros.

   3. objectType: A 10-character field indicating the journal-eligible object type to which the rule applies. The value returned can be one of the following:

      *ALL

      All object types for which journaling is supported.

      *DTAARA

      Data areas

      *DTAQ

      Data queues

      *FILE

      Database files

   4. Operation: A 1-character field indicating the operations on the object type for which journaling attributes are to be inherited from the library. The value returned can be one of the following:

      '0'

      Journaling is inherited for the specified object types that are created into ('1'), moved into ('2'), or restored into ('3') this library. See the descriptions of each of the operations below for further information. Note that operation '0' includes operations '1', '2', and '3' but does not include operation '4'.

      '1'

      Journaling is inherited for the specified object types that are created into this library if other criteria specified for this rule are satisfied.

      '2'

      Journaling is inherited for the specified object types that are moved into this library if the object is not already journaled and other criteria specified for this rule are satisfied.

      '3'

      Journaling is inherited for the specified object types that are restored into in this library if other criteria specified for this rule are satisfied unless the object already exists in the library or the object was journaled when it was saved. If the object already exists in the library, the journaling attributes of the existing object are not changed. If the object was journaled when it was saved, it will retain the journaling attributes it had when it was saved, if possible. If not possible (for example, the journal to which it was journaled when it was saved is not found), the restored object will inherit journaling from the library.

      '4'

      Journaling is inherited for the specified object types that are restored into this library if other criteria specified for this rule are satisfied regardless of the journaling attributes of the object when it was saved unless the object already exists in the library. If the object already exists in the library, the journaling attributes of the existing object are not changed.

   5. ruleAction: A 1-character field indicating whether or not the objects that match the object type, object name, and operation of this rule will be included in the list of objects that inherit journaling from the library. The value returned can be one of the following:

      '0'

      All objects that match the object type, object name, and operation of this rule will be included in the list of objects that will inherit journaling from the library according to the journal inherit rules.

      '1'

      All objects that match the object type, object name, and operation of this rule will be omitted from the list of objects that will inherit journaling from the library.

   6. Images: A 1-character field indicating the kinds of images that are deposited to the journal receiver for changes to objects that inherit journaling from the library because of this rule. The value returned can be one of the following:

      '0'

      The default value for each object type will be used for this journaling attribute when an object inherits journaling from the library. Database files (*FILE) will have both before and after images generated by the system ('2'). Data areas (*DTAARA) and data queues (*DTAQ) will have only after images generated by the system ('1').

      '1'

      Only after images are journaled for an object that inherits journaling from the library.

      '2'

      Both before and after images are journaled for an object that inherits journaling from the library. The value '2' is only valid for data areas (*DTAARA) and database files (*FILE). If '2' is specified and *ALL is specified for Object type, the system will generate both before and after images for data areas and database files and the system will only generate after images for data queues (*DTAQ).

   7. OmtJrnE: A 1-character field indicating the journal entries to be omitted (not deposited to the journal receiver) for changes to objects that inherit journaling from the library because of this rule. The value returned can be one of the following:

      '0'

      The default value for each object type will be used for this journaling attribute when an object inherits journaling from the library because of this rule. No journal entries ('1') will be omitted for data areas (*DTAARA) and data queues (*DTAQ). Open and close journal entries ('2') will be omitted for database files (*FILE).

      '1'

      No journal entries will be omitted for objects that inherit journaling from the library because of this rule.

      '2'

      Open and close journal entries are not deposited for database files (*FILE) that inherit journaling from the library because of this rule. Specifying '2' prevents the use of TOJOBO and TOJOBC entries on the Apply Journaled Changes (APYJRNCHG) and Remove Journaled Changes (RMVJRNCHG) commands, but it saves some storage space in the journal receivers. The value '2' is only valid for database files (*FILE). If '2' is specified and *ALL is specified for Object type, database files will omit open and close journal entries and data areas (*DTAARA) and data queues (*DTAQ) will not omit any journal entries.

   8. The layout of the next fields is dependent on the value returned in the Version field as follows:

      1

      a 2-character reserved field containing hexadecimal zeros.

      2

      the following fields are returned:

      1. rmtJrnFtr: A 1-character field indicating the remote journal filter value for the objects to which this rule applies. The value returned can be one of the following:

         '0'

         The default value of each object type will be used for this journaling attribute when an object inherits journaling from the library. For all object types, the journal entries deposited for the objects that inherit journaling from the library will not be eligible for remote journal filtering by object.

         '1'

         Journal entries deposited for objects for which journaling is inherited from the library because of this rule will not be eligible for remote journal filtering by object.

         '2'

         Journal entries deposited for objects for which journaling is inherited from the library because of this rule will be eligible for remote journal filtering by object.

         When using remote journal filtering by object, journal entries for the object will not be sent to the target system.

         See the Change Remote Journal (CHGRMTJRN) command or the Change Journal State (QjoChangeJournalState) API for more information about remote journal filtering.

      2. a 1-character reserved field containing hexadecimal zeros.

CL var for TEXT (50) (TEXT)

Specifies a 50-character CL variable used to return the text description of the library.

Examples

Assume that the library named TESTLIB was created as follows:

CRTLIB   LIB(TESTLIB)  CRTAUT(*ALL)  TEXT('John Smith library')

Also assume that journaling was started for the library named TESTLIB using the following Start Journal Library (STRJRNLIB) command:

STRJRNLIB LIB(TESTLIB) JRN(TESTLIB/LIBJRN)

PGM Example

DCL   VAR(&CRTAUT)  TYPE(*CHAR)  LEN(10)
DCL   VAR(&JRNSTS)  TYPE(*CHAR)  LEN(1)
DCL   VAR(&JRN)     TYPE(*CHAR)  LEN(10)
DCL   VAR(&JRNLIB)  TYPE(*CHAR)  LEN(10)
RTVLIBD   LIB(TESTLIB)  CRTAUT(&CRTAUT) JRNSTS(&JRNSTS)
          JRN(&JRN) JRNLIB(&JRNLIB)

The RTVLIBD command will return:

• a value of '*ALL ' in program variable &CRTAUT,
• a value of '1' in program variable &JRNSTS,
• a value of 'LIBJRN ' in program variable &JRN, and
• a value of 'TESTLIB ' in program variable &JRNLIB.

Error messages

*ESCAPE Messages

CPF21AD

INHRULES parameter size is too small.

CPF210E

Library &1 not available for reason code &2.

CPF2115

Object &1 in &2 type *&3 damaged.

CPF2150

Object information function failed.

CPF2151

Operation failed for &2 in &1 type *&3.

CPF980B

Object &1 in library &2 not available.

CPF9810

Library &1 not found.

CPF9820

Not authorized to use library &1.

CPF9830

Cannot assign library &1.