HP 3000 Manuals HP 3000 Manuals
Parameter Descriptions -- COBOL
In this subchapter, the System Dictionary parameter types are defined in
COBOL terms. The data declarations that would be used for these
parameters in a COBOL program would be put in the Data Division, as part
of the Working Storage section. Note that a list of names may be passed
in two ways, as shown in examples 1 and 2 in the AttributeListType
parameter type.
AttributeDescription This parameter is a record whose first element
is a four byte integer which identifies an
attribute's data type, and whose second element
is a four byte integer which describes the
attribute's data length. Where the data length
is either fixed or zero, the second element can
be zero.
Example :
01 ATTRIBUTE-PARMS.
05 ATTRIBUTE-TYPE PIC S9(9) COMP.
05 ATTRIBUTE-LENGTH PIC S9(9) COMP.
AttributeEditsType The data type of this parameter corresponds to
the data type of the attribute edit, and may be
as described below.
If this parameter is Boolean data type :
This parameter type is an array with Boolean
values (true or false).
Example :
01 ATTRIBUTE-EDIT-TYPES.
05 BOOLEAN-TYPES PIC (X) OCCURS n TIMES.
The value of LOGGINGFLAG is actually a Pascal
Boolean data type. Therefore, it must be set
to %1 for true or %0 for false.
MOVE %1 TO LOGGINGFLAG. (Set to true)
MOVE %0 TO LOGGINGFLAG. (Set to false)
if this parameter is character data type :
This parameter type is an character array
containing a list of edit values for a
character data type attribute. The byte length
of each edit value is the same as the
attribute's byte length.
Example :
01 ATTRIBUTE-EDIT-TYPES.
05 CHARACTER-TYPES PIC (X) OCCURS n TIMES.
if this parameter is 2-byte integer data type :
This parameter type is an array containing
pairs of 2-byte integer values. Each pair
represents a range of valid integer values for
a 2-byte integer data type attribute.
Example :
01 ATTRIBUTE-EDIT-TYPES.
05 INTEGER-2-TYPES PIC S9(4) OCCURS n TIMES.
If this parameter is 4-byte integer data type :
This parameter type is an array containing
pairs of 4-byte integer values. Each pair
represents a range of valid integer values for
a 4-byte integer data type attribute.
Example :
01 ATTRIBUTE-EDIT-TYPES.
05 INTEGER-4-TYPES PIC S9(9) OCCURS n TIMES.
4-byte floating point data type : not
supported in COBOL.
8-byte floating point data type : not
supported in COBOL.
AttributeListType If this parameter is name type :
This parameter type is a character array
containing the names of entities. Each name in
the list must either be 32 characters long or
be separated from the next name in the list by
at least one blank. Separation by blanks is
optional if the names are 32 characters long.
The length of the list may be up to 8646
characters, and must be terminated with a
semicolon.
Example 1 :
01 ATTRIBUTE-NAME-LIST PIC X(n).
where n is the length of the character string
being passed.
Example 2 :
01 ATTRIBUTE-NAME-LIST.
05 ATTRIBUTE NAME PIC X(32) OCCURS n TIMES.
where n is the number of names being passed.
If this parameter is internal number type :
This parameter is an array of up to 263 four
byte integers. The first four bytes of this
array contain a number N (1 to 262), which is
followed by N numbers. The length of the array
is determined by the number of integers being
passed. The internal numbers are the
attributes' internal numbers.
Example :
01 ATTRIBUTE-ARRAY
05 ATTRIBUTE-NUMBER-LIST PIC S9(9) OCCURS n TIMES.
where n = (the number of internal attribute
numbers in the list) + 1.
AttributeValuesType This parameter type is user defined. It is a
any data type whose fields match the data types
and lengths for the attributes supplied in the
attribute list.
Note : The starting position of each attribute
value in the record must be correctly located.
The locations are described in Appendix C of
this manual, under the heading "Attribute Value
Alignment" .
DateType This parameter type is a 16 character field
containing a date generated by a System
Dictionary intrinsic. The date has the
following format:
YYYYMMDDhhmmsstt
where
YYYY is the year
MM is the month
DD is the day
hh is the hour
ss is the minute
tt is the second
is the tenths of the second
Example :
01 DATE.
05 YEAR PIC 9(4).
05 MONTH PIC 9(2).
05 DAY PIC 9(2).
05 HOUR PIC 9(2).
05 MINUTE PIC 9(2).
05 SECOND PIC 9(2).
05 TENTH-SECONDS PIC 9(2).
DcbType The Dictionary control block is an array of 30
four byte integers, and is used to pass control
information to the intrinsics.
Example :
01 XX-ARRAY.
05 DCB PIC S9(9) COMP OCCURS 30 TIMES.
DictionaryName This parameter should be left justified. If
the name is less than 86 characters, the last
character in the name must be a blank.
Example :
01 DICTIONARY PIC X(86).
EntityListType This parameter specifies a list of entities,
either in name format or in internal number
format.
If this parameter is name type :
This parameter type is a character array
containing the names of entities. Each name in
the list must either be 32 characters long or
be separated from the next name in the list by
at least one blank. Separation by blanks is
optional if the names are 32 characters long.
The length of the list may be up to 198
characters, and must be terminated with a
semicolon.
Example :
01 ENTITYLIST PIC X(n).
where n is the length of the character string
being passed.
If this parameter is internal number type :
This parameter is an array of up to 7 four byte
integers. The first four bytes of this array
contain a number N (1 to 6), which is followed
by N numbers. The length of the array is
determined by the number of integers being
passed. The internal numbers are the entities'
internal numbers.
Example :
01 ENTITY-ARRAY.
01 ENTITYLIST PIC S9(9) COMP OCCURS n TIMES.
where n = (the number of internal numbers in
the list) + 1.
EntityListOutType This parameter type is an array containing up
to six entity names. Each name in the array is
defined by parameter type NameType, and must be
a left justified, right blank filled, 32
character field. The list will be terminated
by a semicolon. The number of elements in the
list is determined by the user, but no more
than six names will ever be returned by an
intrinsic. The maximum number of usable bytes
in this parameter is 193 [(32*6)+1].
Example :
01 ENTITY-ARRAY.
05 ENTITYLIST PIC X(32) OCCURS n TIMES.
where n = (the number of names in the list) +
1.
ItemValueType This parameter type is user defined. It is any
data type whose fields match the data type and
length for the corresponding specified item.
Example :
01 LOGGINGFLAG PIC X.
The value of LOGGINGFLAG is actually a Pascal
Boolean data type. Therefore, it must be set
to %1 for true or %0 for false.
Example :
MOVE %1 TO LOGGINGFLAG. (Set to true)
MOVE %0 TO LOGGINGFLAG. (Set to false)
MessageType This output parameter type is a character array
used for error messages, and is left justified.
Example :
01 MESSAGE PIC X(72).
NameType This parameter type may be used as either an
input or output parameter. If it is used as an
input parameter, the name must be 32
characters, left justified, and right blank
filled. All lower case letters will be
upshifted. All alphanumeric and special
characters may be used in a name EXCEPT those
in the following list:
, ; : . ( ) " = > < ^ !
If the name is an output parameter, it will be
left justified and right blank filled.
Example :
01 ENTITY PIC X(32).
NameOrNumberType This parameter type can pass information in
either name or number format.
If this parameter is name type :
This parameter is a left justified, right blank
filled, 32 character name. All lower case
letters used in the name will be upshifted.
All alphanumeric and special characters may be
used in a name EXCEPT those in the following
list:
, ; : . ( ) " = > < ^ !
Example :
01 ENTITY PIC X(32).
If this parameter is internal number type:
The first four bytes of this array contain the
number 1 (one), followed by a four byte integer
which is the internal number.
Example :
01 ENTITY-ARRAY.
05 ENTITY PIC S9(9) COMP OCCURS 2 TIMES.
Note :
If the parameter is: the internal number
should be:
an attribute the attribute's internal
number
a domain the domain's internal
number
an entity the entity's internal
number
an entity type the entity type's
internal number
a relationship class the relationship class'
internal number
a scope the scope's internal
number
a version the version's internal
number
NewEntityListType If this parameter is name type :
This parameter type is a character array
containing the names of entities. Each name in
the list must either be 32 characters long or
be separated from the next name in the list by
at least one blank. Separation by blanks is
optional if the names are 32 characters long.
The length of the list may be up to 198
characters, and must be terminated with a
semicolon.
Example :
01 NEWENTITYLIST PIC X(n).
If this parameter is internal number type :
This parameter is an array of up to 7 four byte
integers. The first four bytes of this array
contain a number N (2 to 6), which is followed
by N numbers. The length of the array is
determined by the number of integers being
passed. The internal numbers are the entities'
internal numbers.
Example :
01 NEWENTITY-ARRAY.
05 NEWENTITYLIST PIC S9(9) COMP OCCURS n TIMES.
where n = (the number of internal numbers in
the list) + 1.
NewNameType This parameter type is an array which contains
either one or two names as defined by parameter
type NameType. The first name is an internal
name and is required. If an external name for
the definition is desired, a second name may be
included in the array. This name fills
positions 1 through 32 of second name of the
array, and, like the first name, must be left
justified and right blank filled. If a second
name is not desired, the name space must be
filled with blanks.
Example :
01 ENTITY-ARRAY.
05 ENTITY PIC X(32) OCCURS 2 TIMES.
All alphanumeric and special characters may be
used in a name EXCEPT those in the following
list:
, ; : . ( ) " = > < ^ !
NewRelationshipTypeList If this parameter is name type :
This parameter type is a character array
containing the entity types involved in a
relationship type. Each name in the list must
either be 32 characters long or be separated
from the next name in the list by at least one
blank. Separation by blanks is optional if the
names are 32 characters long. The length of
the list may be up to 198 characters, and must
be terminated with a semicolon.
Example :
01 ENTITY-ARRAY.
05 RELATIONSHIPTYPE PIC X(32) OCCURS n TIMES.
where n = the number of names in the
relationship type.
If this parameter is internal number type :
This parameter is an array of up to 7 four byte
integers. The first four bytes of this array
contain a number N (1 to 6), which is followed
by N numbers. The length of the array is
determined by the number of integers being
passed. The internal numbers are the entity
types' internal numbers.
Example :
01 REL-TYPE-ARRAY.
05 RELATIONSHIPTYPE PIC S9(9) OCCURS n TIMES.
where n = (the number of numbers in the list) +
1.
RelationshipTypeList If this parameter is name type :
This parameter type is a character array
containing the entity types involved in a
relationship type. Each name in the list must
either be 32 characters long or be separated
from the next name in the list by at least one
blank. Separation by blanks is optional if the
names are 32 characters long. The length of
the list may be up to 198 characters, and must
be terminated with a semicolon.
Example :
01 REL-TYPE-ARRAY.
05 RELATIONSHIPTYPE PIC X(32) OCCURS n TIMES.
where n = (the number of names in the list) +
1.
If this parameter is internal number type :
This parameter is an array of up to 7 four byte
integers. The first four bytes of this array
contain a number N (1 to 6), which is followed
by N numbers. The length of the array is
determined by the number of integers being
passed. The internal numbers are the entity
types' internal numbers.
Example :
01 REL-TYPE-ARRAY.
05 RELATIONSHIPTYPE PIC S9(9) OCCURS n TIMES.
where n = (the number of numbers in the list) +
1.
RelationshipTypeOutList This parameter type is a character array
containing up to six entity types (names)
involved in a relationship type. Each name in
the array is defined by parameter type
NameType, and must be a left justified, right
blank filled, 32 character field. The list
will be terminated by a semicolon. Therefore,
if there are six names in the array, the
semicolon will be located in the first byte of
the seventh field, as shown in the example
below. The seventh field will not be right
blank filled.
Example :
01 OUT-REL-ARRAY.
05 RELATIONSHIPTYPE PIC X(32) OCCURS n TIMES.
RetrievalIDType This parameter type contains information
identifying what is to be retrieved.
Example :
01 ID-ARRAY.
05 RETRIEVALIDTYPE PIC S9(9) OCCURS 20 TIMES.
ScopeAccessType This parameter type contains a four byte
integer which is the ScopeAccess number of the
scope. It specifies the access a scope has to
an entity or a relationship. The legal values
are:
1 = Read access
2 = Read and Modify access
3 = Create, Delete, Read, and Modify
access
Example :
01 SCOPEACCESS PIC S9(9) COMP.
ScopePasswordType This parameter type contains a 32 character
array which must be right blank filled.
Trailing blanks are not considered part of the
password. However, the password may contain
embedded blanks, or be all blanks (no
password).
Note : All alphanumeric and special characters
may be used in passwords.
Example :
01 PASSWORD PIC X(32).
ScopeRightsType This parameter is an array of up to 7 four byte
integers. The first four bytes of this array
contain a number N (1 to 6), which is followed
by N scope right numbers. The length of the
array is determined by the user.
Example :
01 RIGHTS-ARRAY.
05 SCOPERIGHTS PIC S9(9) OCCURS n TIMES.
where n = (the number of scope rights in the
array) + 1. Note : Scope rights are assigned
as follows:
1 = Secure capability
2 = Extend capability
3 = Create capability
4 = Read capability
5 = Domain capability
6 = Version Control capability
StatusType This parameter type is a 28 byte array (7 four
byte integers) containing information
indicating the success or failure of an
intrinsic call. Every intrinsic returns this
information. The first 16 bytes are the same
for each intrinsic, as shown below.
Table 3-1. STATUS CONTENTS (COBOL)
-------------------------------------------------------------------
| | |
| Bytes | Contain |
| | |
-------------------------------------------------------------------
| | |
| 1 - 4 | The System Dictionary condition code (error |
| | message number) |
| | |
-------------------------------------------------------------------
| 5 - 8 | |
| | The subsystem code number: |
| | |
| | 0 = No Subsystem Error |
| | 1 = MPE |
| | 2 = IMAGE |
| | 3 = SORT |
-------------------------------------------------------------------
| | |
| 9 - 12 | The subsystem error code. (e.g. the IMAGE |
| | error code) |
| | |
-------------------------------------------------------------------
| | |
| 13 - 16 | The intrinsic number |
| | |
-------------------------------------------------------------------
The contents of the remaining bytes (17 - 28)
depend on the intrinsic being called. The
description of each intrinsic which uses these
bytes contains a continuation of this table,
which shows how they are used in that
particular intrinsic.
Example :
01 STATUS ARRAY.
05 STATUS PIC S9(9) COMP OCCURS 7 TIMES.
______________________________________________
NOTE Every System Dictionary intrinsic which
is used to retrieve a list of items (e.g.
SDFindRelList, SDGetDomainList,
SDGetRelVarAttr) will return System
Dictionary error number 24 to the first
four bytes of the Status parameter after
the last item in the list has been
retrieved. This number, however, is not
really an intrinsic "error" , but a value
which may be used for program control
(e.g. testing within a loop). Because
the value does not change until after the
last item in the list is retrieved, the
intrinsic is actually called one more
time than the number of items in the
list.
For example, the intrinsic
SDGetDomainList is used in a dictionary
which has six domains. Assuming no
dictionary errors, the first four bytes
of the Status parameter will be 0 during
the first six calls (0 = no dictionary
errors). On the seventh call, however,
there are no more domains to retrieve,
and the value 24 will be returned,
indicating "end-of-list" .
______________________________________________
ValueLine This output parameter type returns a line of
value text from a variable length attribute.
It is an 80 character data item which is left
justified and right blank filled.
Example :
01 VALUE PIC X(80).
ValueText This input parameter type specifies a variable
length character string (text) being assigned
to a variable length attribute. It is a
character data item whose length is determined
by the user.
Example :
01 VALUE PIC X(n).
where n is the length of the character string
being passed.
VersionStatusType This parameter type is a four-byte integer
specifying the status of a version. Valid
values for the version statuses are:
1 = Test status
2 = Production status
3 = Archival status
Example :
01 VERSIONSTATUS PIC S9(9) COMP.