Using API / Subprogram PALUD42

The subprogram PALUD42 is delivered with Predict as standard and is stored in library SYSDIC. It contains parameter data area PALPUD42, which is used for accessing user-defined object types in 4.2 format.

If you wish to access data still in 3.2 format, see Compatibility with Predict Version 3.2.

If you wish to access data still in 3.3, 3.4 or 4.1 format, see Compatibility with Predict Version 3.3, 3.4 and 4.1.

This section covers the following topics:


Parameter Data Area PALPUD42

If API functions are to be called from a program, the parameter data area PALPUD42 must be included in the data definition:

              :
              :
   DEFINE DATA
          LOCAL USING PALPUD42     /* API CALLNAT parameter
          LOCAL
              :
              :
  

Field Definitions in PALPUD42

Some fields defined in the parameter data area PALPUD42 can be used both as input or as output fields. These fields may be read and modified by both the Predict program PALUD42 (that executes API functions) and user programs. Other fields may only be used as either input or output fields.

The description of the different functions in the following sections contains lists of the fields that are used as input fields and fields that are used as output fields by the program PALUD42.

Many of the fields defined in the parameter data area PALPUD42 are defined by redefining the field API-INFO(*).

Executing an API Function

From within any program, an API function is executed by calling the program PALUD42 with a CALLNAT statement and the field #FUNCTION containing the code of the function that is to be executed (GA, GV, GO, etc.). All fields of the parameter data area PALPUD42 must be specified with the CALLNAT statement:

CALLNAT 'PALUD42'
#FUNCTION
#OBJECT-TYPE
#CHILD-TYPE
#OBJECT-ID
#OBJECT-COMPLETE
#MAINTENANCE-ACTIVITY
#RESP-GR
#SYSDIC-USER
#INTERNAL
#API-INFO(*) 

When calling a function, make sure that all the values needed to execute a function are passed.

Condition Codes

After execution of PALUD42, a response code is returned in the field #RESPONSE-GR.

Field Name Format Description
#RESPONSE-GR    
#RESP-CODE I2 Predict error message number. The full text of the respective message can be displayed by entering ? DICnnnn in the command line of Predict (where nnnn is the message number).
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Sample Program PALTEST

The sample program PALTEST, which uses all API functions, is delivered with Predict. Enter PALTEST at the NEXT prompt in your Predict environment to see what PALTEST does.

Retrieval Functions

This section covers the following topics:

GA - Get Attributes of Object Type

The function returns the metadata definitions of the object type. The following information is retrieved for different attributes:

  • Attribute name,

  • will upper/lower case translation be performed for alphanumeric fields,

  • the data type (alphanumeric or numeric) of attributes,

  • the length of attribute fields (for numeric fields including the decimal places),

  • decimal places of numeric fields.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#ATTR-NAME (1:80) A32 Name of the attribute
#UP-LOW (1:80) A1 Upper/lower case conversion
#FORMAT (1:80) A1 Data type of attribute field
#LENGTH (1:80) N2 Length of attribute field
#DEC-POS (1:80) N1 Number of decimal places
#IN-COL (1:80) N8 Line/column for attribute name and value
#SCR-NUM (1:80) N2 Number of the screen in which the attribute is used
#ED-MASK (1:80) N2 Type of the edit mask
#RULE (1:80) A2 Type of the verification rule
#OCC (1:80) N2 Position of the attribute within the record
#MAINTENANCE-DATE (1) T Date and time of creation
#MAINTENANCE-ACTION(1) A8 ID of user who created the object
#MAINTENANCE-DATE (2) T Date and time of modification
#MAINTENANCE-ACTION(2) A8 ID of user who modified the object
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

GL - Get Linked Objects

This function retrieves all objects that are linked to a specified object via an association code. All links to an object are stored in link records. Up to 50 objects can be stored in one link record. A maximum of 999 link records per object for one association code can exist.

Each call of the function reads one link record. An input loop must be coded to read more than one link record.

The fields #CHILD-NUMBER and #CHILD-COUNTER are used to specify how many lines of the extended description are read (see example below).

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Predict Object Type
#ASSO-TYPE A2 Predict Association Code
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#SYSDIC-USER A250 User area
#CHILD-COUNTER N4 Must be incremented for each call of the GL function ( if called more than once; see example below).

Note:
#CHILD-COUNTER=1 after the first record of linked objects has been read.

Output Fields

Field Name Format Description
#CHILD-NUMBER N4 Number of existing link records; is returned after the first execution of the function. Can be used as end value of a loop if more than one child record is to be read.
#CHILD-NAME (1:50) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Example

   DEFINE DATA LOCAL
          USING PALPUD42
   END-DEFINE
   *
   #FUNCTION      = 'GL'
   #OBJECT-TYPE   = 'OO'
   #OBJECT-ID     = 'ULH-OO-FILLED'
   *
   REPEAT
     CALLNAT 'PALUD42' #FUNCTION #OBJECT-TYPE #CHILD-TYPE #OBJECT-ID
                       #OBJECT-COMPLETE #MAINTENANCE-ACTIVITY #RESP-GR
                       #SYSDIC-USER #INTERNAL #API-INFO(*)
   *
      DISPLAY #CHILD-NAME(*)
      ADD 1 TO #CHILD-COUNTER
      IF #CHILD-COUNTER > #CHILD-NUMBER
         ESCAPE BOTTOM
   LOOP
   END
   

GO - Get Owners of Object

The function reports all owners of an object.

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#OWNER (1:99) A32 Owner IDs
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

GV - Get Values of Attributes

The function reports attribute values of an object. The following values are retrieved:

  • Numeric attribute values.

  • Alphanumeric attribute values.

  • Abstract and keywords.

  • Whether owners or descriptions are specified for the object.

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#OWNER-YN A1 Y if owner is specified, else N
#DESC-YN A1 Y if description is specified, else N
#MAINTENANCE-DATE (1) T Date and time of creation
#MAINTENANCE-ACTION(1) A8 ID of user who created the object
#MAINTENANCE-DATE (2) T Date and time of modification
#MAINTENANCE-ACTION(2) A8 ID of user who modified the object
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

HO - Get Owners of Object

This function reports all owners of an object. The object is put into HOLD while the function is executed.

If the owner list of an object is to be to be modified, this function should be called first. There are two reasons for this recommendation:

  • The object is put in HOLD.

  • The modify function MO always overwrites the complete owner list. If for example only one owner is added or changed, all other owners would be overwritten with blanks. Calling HO before modifying any owner ensures that all owners are stored in the respective fields of PALPUD42 and therefore kept when old definition is overwritten.

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#OWNER (1:99) A32 Owner IDs
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

HV - Hold Values

The function reports attribute values of an object and puts the object into HOLD while the function is executed. The following values are retrieved:

  • Numeric attribute values.

  • Alphanumeric attribute values.

  • Abstract and keywords.

  • Whether owners or descriptions are specified for the object.

If attribute values of an object are to be to be modified, this functions should be called first. There are two reasons for this recommendation:

  • The object is put in HOLD.

  • The modify function MV always overwrites the complete attribute definition of an object. If only one attribute is changed, all other attributes would be overwritten with blanks. Calling the function HV before modifying any attribute values ensures that the old attribute values are stored in the respective fields of PALPUD42 and therefore kept when the old definition is overwritten.

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Predict Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#OWNER-YN A1 Y if owner is specified, else N
#DESC-YN A1 Y if description is specified, else N
#MAINTENANCE-DATE (1) T Date and time of creation
#MAINTENANCE-ACTION(1) A8 ID of user who created the object
#MAINTENANCE-DATE (2) T Date and time of modification
#MAINTENANCE-ACTION(2) A8 ID of user who modified the object
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

PV - Return Predict Version

The function PV returns the current Predict Version.

Input Fields

None.

Output Fields

Field Name Format Description
#Predict-VERSION N3 Current Predict version

Maintenance Functions

This section covers the following topics:

AV - Add Object

This function adds an object with its attribute values. The following parameters are returned by PALUD42 because their values may have been converted to upper case: #OBJECT-ID, #ALPHA-VALUES, #NUM-VALUES, #SHORT-COMMENTS and #KEYWORDS.Rules and Hints

Note:
If return code 1, 2 or 3 is returned in the field #OBJECT-COMPLETE, inconsistent data has been added to the dictionary. The functions MO or MD must then be called to add an owner or extended description to the object. See also Rules and Hints.

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used
#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#OBJECT-COMPLETE A1 Whether object has been defined completely. Valid values:
  • 0 - Complete

  • 1 - Owner missing (force)

  • 2 - Desc missing (force)

  • 3 - Owner and description missing (force)

#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used
#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

D - Delete an Object

This function deletes an object, all links to child objects, and all links from parent objects to the deleted object.

Note:
The function D (Delete) of Version 3.4 corresponds to the function S (Scratch) of Version 3.2. The Delete functionality of Version 3.2 has not been available since Predict Version 3.3.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used

Output Fields

Field Name Format Description
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

LO - Link Object

This function adds one entry to the child list of an object. When the list is sorted, the new entry is inserted in its proper place. If an object with the given #CHILD-NAME already exists, a message is issued.

#CHILD-NAME is returned by PALUD42 because the child name (ID) may have been converted to upper case.

Note:
Attributes for associations cannot be maintained with this function, i.e. the values of the attributes are not checked.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#CHILD-TYPE A2 Predict Child Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#CHILD-NAME (1:1) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#CHILD-NAME (1:1) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

ML - Modify Links

The function modifies the child list of objects. #CHILD-NAME will be returned by PALUD42 because the child names (IDs) may have been converted to upper case. The following rules apply:

  • Before PALUD42 is called with the function ML for the first time, the parameter #CHILD-INFO must be set to F. This has the effect that

    • the old child records are deleted, and

    • the first child record is stored.

    We therefore recommend assigning at least one child to the parameter #CHILD-NAME before PALUD42 is called for the first time (see example below).

  • After the first call of PALUD42, #CHILD-INFO must be reset (as shown in the example below).

  • Up to 50 child objects can be specified in one call of ML. If there are more entries in the child list, the function must be called again.

  • After the new child objects have been transferred (or while transferring the last new child objects), the parameter #CHILD-INFO must be set to L (last record). This ensures that - if there are attributes for the link and if child objects have been deleted from the list - the corresponding attribute records are purged.

Note:
Attributes for associations cannot be maintained with this function, i.e. the values of the attributes are not checked.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#CHILD-TYPE A2 Predict Child Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#CHILD-INFO A1 F: first access to the child records
L: last access to the child records
#CHILD-NAME (1:50) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#CHILD-COUNTER N4 Number of current child records
#CHILD-NAME (1:50) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Example

   MOVE 'F' TO #CHILD-INFO /* first record
   MOVE 'child1' TO #CHILD-NAME(1)
   CALLNAT 'PALUD42' 'ML'  #CHILD-INFO ... #CHILD-NAME(*) ....
   RESET #CHILD-INFO
   MOVE 'child51' TO #CHILD-NAME(1)
   CALLNAT 'PALUD42' 'ML'  #CHILD-INFO ... #CHILD-NAME(*) ....
   MOVE 'child101' TO #CHILD-NAME(1)
   MOVE 'L' TO #CHILD-INFO /* letzter Record
   CALLNAT 'PALUD42' 'ML'  #CHILD-INFO ... #CHILD-NAME(*) ....
           /*Delete records of deleted link records
   END TRANSACTION
  

MO - Modify Owners

This function modifies owners of an object. The parameter #OWNER is returned by PALUD42 because owner names may have been converted to upper case.

If the owner list of an object is to be modified, the function HO should be called first. There are two reasons for this recommendation:

  • The object is put in HOLD.

  • The modify function MO always overwrites the complete owner list. If - for example - only one owner is added or changed, all other owners would be overwritten with blanks. Calling HO before modifying any owner ensures that all owners are stored in the respective fields of PALPUD42 and therefore kept when the old definition is overwritten.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#OWNER (1:99) A32 Owner ID
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#OWNER (1:99) A32 Owner ID
#OBJECT-COMPLETE A1 Whether object has been defined completely. Valid values:
  • 0 Complete

  • 1 Owner missing (force)

  • 2 Description missing (force)

  • 3 Owner and description missing (force)

#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

MV - Modify Values of Attributes

This function changes values of attributes. The following parameters are returned by PALUD42 because their values may have been converted to upper case: #OBJECT-ID, #ALPHA-VALUES, #NUM-VALUES, #SHORT-COMMENTS and #KEYWORDS.

If attribute values of an object are to be modified, the function HV should be called first. There are two reasons for this recommendation:

  • The object is put in HOLD.

  • The modify function MV always overwrites the complete attribute definition of an object. If only one attribute is changed, all other attributes would be overwritten with blanks. Calling the function HV before modifying any attribute values ensures that the old attribute values are stored in the respective fields of PALPUD42 and therefore kept when the old definition is overwritten

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used
#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#OWNER-YN A1 Y if owner is specified, else N
#DESC-YN A1 Y if owner is specified, else N
#OBJECT-COMPLETE A1 Whether object has been defined completely. Valid values:
  • 0 Complete

  • 1 Owner missing (force)

  • 2 Description missing (force)

  • 3 Owner and description missing (force)

#ALPHA-VALUES (1:80) A78 Values of alphanumeric fields
#NUM-VALUES (1:80) P27 Values of numeric fields
#SHORT-COMMENTS (1:16) A30 Abstract
#KEYWORDS (1:32) A32 Keywords
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Example

   CALLNAT 'PALUD42' 'HV' ... alpha-value
   MOVE 'abc' TO alpha-value
   CALLNAT 'PALUD42' 'MV' ... alpha-value
  

N - Rename Objects

The function renames objects. The parameter #NEW-OBJECT-ID is returned by PALUD42 because the new object ID may have been converted to upper case.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) not used
#NEW-OBJECT-ID A32 New object ID for rename function

Output Fields

Field Name Format Description
#NEW-OBJECT-ID A32 New object ID for rename function
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

ST - Find Objects of Different Types with Same Name

Predict objects of different types can have the same name (ID). The function ST finds all objects of different types having the same name.

Input Fields

Field Name Format Description
#OBJECT-ID A32 Object ID

Output Fields

Field Name Format Description
#NUMBER-OF-TYPES N3 Number of objects of different types having the same ID
#OBJECT-TYPES (1:130) A2 Object type code
#OBJECT-TITLE (1:130) A17 Titles of objects types in upper case
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

UO - Unlink Object

The function removes one entry of the child list of an object. If an object with the given #CHILD-NAME is not found, a message is issued.

#CHILD-NAME is returned by PALUD42 because the child name (ID) may have been converted to upper case.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#CHILD-TYPE A2 Predict Child Type
#OBJECT-ID A64 consists of:
#OBJECT-NAME (A32) Predict Object ID
#OBJECT-FILE-NAME (A32) Predict Object ID of a file (only used for elementary fields)
#CHILD-NAME (1:1) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#CHILD-NAME (1:1) A64 consists of:
Object ID of linked child (A32)  
Object ID of a file (A32) (only used for elementary fields)
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Compatibility with Predict Version 3.2

To ensure that existing user programs continue to be executable without changing the parameter data area, the program PALUD is still available (along with the parameter data area PALPUD). If you wish to use PALUD, you must ensure that the metadata of the corresponding user-defined object has the format of version 3.2.

Note:
The program PALUD returns a maximum of 24 keywords for one object ID.

This section covers the following topics:

API Functions of Version 3.2

The following functions are still supported with Predict Version 4.2 to ensure compatibility with Version 3.2:

GD - Get Extended Description

This function retrieves the extended description of an object. An extended description can contain more than one record. Each call of the function reports one record. A loop must be coded to read more than one record. The fields #DESC-NUMBER and #DESC-COUNTER are used to specify how many lines of the extended description are read (see description below).

Input Fields

Field Name Format Description
#OBJECT-TYPE  A2 Predict Object Type
#OBJECT-ID A32 Predict Object ID
#SYSDIC-USER A250 User area
#DESC-COUNTER N4 Must be incremented for each call of the GD function if GD is called more than once (see example below). Note that #DESC-COUNTER is 0 after the first record of an extended description has been read.

Output Fields

Field Name Format Description
#DESC-NUMBER N4 Number of existing description records. #DESC-NUMBER is returned after the function has been executed first. Can be used as end value in a loop if more than one record of an extended description is to be read.
#EXT-DESCRIPTION (1:27) A76 27 lines of description
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Example

   DEFINE DATA LOCAL
          USING PALPUD
   END-DEFINE
   *
   #FUNCTION      = 'GD'
   #OBJECT-TYPE   = 'OO'
   #OBJECT-ID     = 'ULH-OO-FILLED'
   *
   REPEAT
     CALLNAT 'PALUD' #FUNCTION #OBJECT-TYPE #CHILD-TYPE #OBJECT-ID
                     #OBJECT-COMPLETE #MAINTENANCE-ACTIVITY #RESP-GR
                     #SYSDIC-USER #INTERNAL #API-INFO(*)
   *
      DISPLAY (ES=ON) #EXT-DESCRIPTION(*)
      ADD 1 TO #DESC-COUNTER
      IF #DESC-COUNTER > #DESC-NUMBER
         ESCAPE BOTTOM
   LOOP
   END

MD - Modify Description

This function deletes the existing extended description of an object and adds a new extended description. #EXT-DESCRIPTION are returned by PALUD because the extended description may have been converted to upper case. The following rules apply:

  • Before PALUD is called for the first time with the function MD, #DESC-INFO must be set to F. This has the effect

    • that the old extended description is deleted, and

    • that a first record of the new extended description is stored.

    We therefore recommend assigning at least one line of an extended description to #EXT-DESCRIPTION before PALUD is called for the first time (see example below).

  • After the first call of PALUD, #DESC-INFO must be reset (as shown in the example below).

  • Before any new records are stored, the old extended description is purged.

  • Up to 27 lines of description can be specified in one call of MD. If more lines are to be added, the function must be called again.

  • After transferring a new extended description, the parameter #DESC-INFO must be set to L (last line) and an additional call of PALUD must be performed before the END OF TRANSACTION. This ensures:

    • the status information of the respective object is updated

    • the user exit U-DESC is executed (if activated).

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A32 Object ID
#DESC-INFO A1 Specifies first (F) and last (L) access of extended description
#EXT-DESCRIPTION (1:27) A76 Up to 27 lines of description can be specified in one call of MD
#SYSDIC-USER A250 User area

Output Fields

Field Name Format Description
#DESC-COUNTER N4 Number of current description record
#EXT-DESCRIPTION (1:27) A76 Up to 27 lines of description can be specified in one call of MD
#OBJECT-COMPLETE A1 Whether object has been defined completely. Valid values:
  • 0 Complete

  • 1 Owner missing (force)

  • 2 Description missing (force)

  • 3 Owner and description missing (force)

#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Example

   MOVE 'F' TO #DESC-INFO /* First record
   MOVE 'abc' TO #EXT-DESCRIPTION(1)
   CALLNAT 'PALUD' 'MD'  #DESC-INFO ... #EXT-DESCRIPTION(*) ....
   RESET #DESC-INFO
   MOVE 'def' TO #EXT-DESCRIPTION(1)
   CALLNAT 'PALUD' 'MD'  #DESC-INFO ... #EXT-DESCRIPTION(*) ....
   MOVE 'L' TO #DESC-INFO /* Last record
   CALLNAT 'PALUD' 'MD'  #DESC-INFO ... #EXT-DESCRIPTION(*) ...
        /* ensures update of status info and execution of U-DESC (if activated)...
   END TRANSACTION

S - Scratch an Object

This function deletes an object, all links to child objects, and all links from parent objects to the deleted object.

Note:
The function D (Delete) of Version 3.3 corresponds to the function S (Scratch) of Version 3.2. The Delete functionality of Version 3.2 has not been available since Predict Version 3.3.

Input Fields

Field Name Format Description
#OBJECT-TYPE A2 Predict Object Type
#OBJECT-ID A32 Object ID

Output Fields

Field Name Format Description
#SYSDIC-USER A250 User area
#RESP-CODE I2 Predict error message number
#RESP-TEXT1 A34 Text for parameter 1 used in the error message
#RESP-TEXT2 A34 Text for parameter 2 used in the error message

Compatibility with Predict Version 3.3, 3.4 and 4.1

To ensure that existing user programs continue to be executable without changing the parameter data area, the program PALUD33 is still available (along with the parameter data area PALPUD33).