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

• Executing an API Function

• Condition Codes

• Sample Program PALTEST

• Retrieval Functions

• Maintenance Functions

• Compatibility with Predict Version 3.2

• Compatibility with Predict Version 3.3, 3.4 and 4.1

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.

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

• GL - Get Linked Objects

• GO - Get Owners of Object

• GV - Get Values of Attributes

• HO - Get Owners of Object

• HV - Hold Values

• PV - Return Predict Version

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

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

PV - Return Predict Version

The function PV returns the current Predict Version.

Input Fields

None.

Output Fields

Maintenance Functions

This section covers the following topics:

• AV - Add Object

• D - Delete an Object

• LO - Link Object

• ML - Modify Links

• MO - Modify Owners

• MV - Modify Values of Attributes

• N - Rename Objects

• ST - Find Objects of Different Types with Same Name

• UO - Unlink Object

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

Input Fields

Output Fields

D - Delete an Object

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

Input Fields

Output Fields

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.

Input Fields

Output Fields

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.

Input Fields

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

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

Output Fields

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.

This section covers the following topics:

• API Functions of Version 3.2

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
• MD - Modify Description
• S - Scratch an Object

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

Output Fields

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

Output Fields

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.

Input Fields

Output Fields

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).