Help on User Objects

User objects are catalogued entities, a number of which can be created by a user to conveniently hold small amounts of data.

User objects may be temporary or permanent and can be created, saved, selected and deleted as with other entities in the catalogue. They can be given access permissions and can be given aliases.

Data storage within a user object is divided into two data sets (BASIC and UDATA), and each of these sets is divided into 254 'items' which can be addressed by number. Data stored in user objects can be displayed or read into SCL variables, allowing it to be copied into another user object for example.

Naming user objects
Structure of user objects
Handling user objects
User object permissions
Storing data in user objects
Reading data from user objects
Copying user objects

1. Naming user objects

The name of a user object is of the form:

primary_name(secondary_name)

where
primary_name is up to 31 characters in length
secondary_name is up to 12 characters in length

The primary_name is the unique identifier of the user object within the username. The secondary_name, which may be omitted, identifies the use of the object, for example: DATASET1(HOUSEKEEPING) and DATASET2(HOUSEKEEPING).

The secondary name may be chosen freely, but must not be one of the reserved names: ACCOUNT, FSD, or LIBRARY LIST. DISPLAY_USER_DETAILS(COMPONENTS=UO) outputs the secondary name of each user object owned by the current user, so that the name can be used to conveniently identify all objects of the same type.

2. Structure of user objects

A user object consists of two distinct sets of data which are held at the object node in the catalogue. The sets have standard names: BASIC and UDATA. Often only one of these sets, the BASIC set, is used, and the default in the commands to access and display data held user objects is BASIC.

Each set can contain a maximum of 254 different items, each identified by an item number in the range 1 to 254. In most applications corresponding data items in UDATA and BASIC will have the same item number. Each item of data can contain up to 255 bytes of information, subject to an overall limit of 1500 bytes of data held at the user object node. This limit must include an overhead of 4 bytes for each data item in each set.

The user object may thus be thought of as a 2 by 254 string array, the elements of which are variable in length from 1 to 255 bytes. Because of the size limit, not all elements can contain data at once, and for efficiency it is recommended that the size of data is kept well below the 1500 byte limit.

3. Handling user objects

A user object created by CREATE_USER_OBJECT is temporary, so must be saved using SAVE_USER_OBJECT if required beyond the end of the current SCL block. Because the user object is held in the catalogue it is more efficient to access it by local name rather than its catalogued name, and to update it while it is temporary. The local name is obtained using the create command or it can be selected after creation using SELECT_USER_OBJECT. Should a permanent user object be no longer required then it should be deleted with DELETE_USER_OBJECT, to reduce the information held in the catalogue.

3.1 CREATE_USER_OBJECT(CRUO)
3.2 SAVE_USER_OBJECT(SVUO)
3.3 SELECT_USER_OBJECT(SUO)
3.4 DELETE_USER_OBJECT(XUO)

3.1 CREATE_USER_OBJECT(CRUO)

This command creates a temporary user object. User objects may be used to hold small amounts of data without the need to create a file. Up to 1500 bytes of information may be stored in a user object but it is recommended that much smaller amounts of data be stored in them.

CREATE_USER_OBJECT(
@ literal @	NAME	= @ mandatory @,
@ ref int @	LNAME	= @ mandatory @,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object. The (secondary_name) qualifier is optional and is used to indicate the type of object. The name can be freely chosen, but must not be one of the names: FSD, ACCOUNT or LIBRARY LIST. = primary_name(secondary_name) the user object name, where primary_name is up to 31 characters and secondary_name is up to 12 characters.	None, the parameter is mandatory
LNAME	Specifies the local name for the user object. =local_name the local name which should be used to reference the user object within the current and inner SCL blocks	None, the parameter is mandatory

Example

CREATE_USER_OBJECT(NAME=WORKPOOL(FILESET),
                   LNAME=POOL)

creates a user object with primary name WORKPOOL. The secondary name FILESET has been chosen to indicate that a set of filenames are stored in the user object.

The local name POOL should be used to reference the user object, by using *POOL as the NAME parameter in subsequent SCL commands.

3.2 SAVE_USER_OBJECT(SVUO)

This command, which is available with the VME System Programming Option, makes a temporary user object permanent. All the data held at the user object is saved.

SAVE_USER_OBJECT(
@ literal @	NAME	= @ mandatory @,
@ response @	RESPONSE = RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object to be saved = user_object_name normally of the form *localname where the local name was obtained when the user object was created.	None, the parameter is mandatory

Example

SAVE_USER_OBJECT(NAME=*W5)

saves the user object identified by the local name W5. Such a user object would have been created as a temporary object using, for example,

CREATE_USER_OBJECT(NAME=WEEK5(SALES),
                   LNAME=W5)

3.3 SELECT_USER_OBJECT(SUO)

This command provides a local name for a user object. The local name should be used when referring to the user object in the current and any inner SCL blocks, using the form *localname. The command is usually used to select an existing user object, but if the specified user object does not exist then a new, temporary user object will be created.

SELECT_USER_OBJECT(
@ literal @	NAME	= @ mandatory @,
@ ref int @	LNAME	= @ mandatory @,
.....
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object. The (secondary_name) qualifier is optional and is used to indicate the type of object. The name can be freely chosen, but must not be one of the names: FSD, ACCOUNT or LIBRARY LIST = primary_name(secondary_name) the user object name, where primary_name is up to 31 characters and secondary_name is up to 12 characters	None, the parameter is mandatory
LNAME	Specifies the local name for the user object = local_name the local name which should be used to reference the user object within the current and inner SCL blocks	None, the parameter is mandatory

Example

SELECT_USER_OBJECT(NAME=:USER.WORKPOOL(FILESET),
                   LNAME=POOL)

selects the user object identified by :USER.WORKPOOL(FILESET) and gives it the local name POOL.

3.3 DELETE_USER_OBJECT(XUO)

This command deletes the specified user object. The object and its data become temporary until the end of the outermost SCL block in which it was selected, or created.

DELETE_USER_OBJECT(
@ literal @	NAME	= @ mandatory @,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory

Example

BEGIN
      SELECT_USER_OBJECT(NAME=WEEK10(STATSCOUNTS),
                         LNAME=W10)
      .....
      DELETE_USER_OBJECT(NAME=*W10)
      .....
END

The effect of DELETE_USER_OBJECT is to make the user object with local name W10 temporary until the end of the outermost SCL block in which it was selected (i.e. the final END in the above example), when it is deleted.

4. User object permissions

To allow access to a user object from a username or usernames other than the controlling username, a set of permissions can be associated with the user object using SET_USER_OBJECT_PERMISSIONS. The permissions, which indicate whether the object can be read, written to, or deleted, can be generally applicable to all other users or to another specific user. Having obtained access permissions, another user can simplify his access by obtaining an alias to the user object with CHANGE_USER_OBJECT_ALIAS. This is particularly the case when specific permissions are granted, when the system generated alias can given a more meaningful name.

The permissions associated with a particular user object may be displayed using

DISPLAY_USER_OBJECT_DETAILS(NAME=object_name,
                            COMPONENTS=PRIV,
                            LEVEL=STD)

and a complete list of user objects, including aliases, is displayed using

DISPLAY_USER_DETAILS(COMPONENTS=UO,
                     ALIAS_LEVEL=STD)

4.1 CHANGE_USER_OBJECT_PERMISSIONS(CUOP)

This command changes the permissions associated with the specified user object. The permissions may be granted to one user or to all users. Permissions may be created, replaced or deleted. If a specific permission to a single username is created, the system generates an alias under that username with a name ICL9NALIAS<date and time> associated with the relationship. A change in general permissions does not affect any specific permissions granted.

CHANGE_USER_OBJECT_PERMISSIONS(
@ literal @	NAME	= ,
@ literal @	ACCESS	= ,
@ literal @	USERNAME	= ,
.....
@ response @	RESPONSE = RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user_object = user_object_name This is of the form *localname, primary_name or primary_name(secondary_name)	*, meaning the current active user_object
ACCESS	Specifies the access permissions to be given. If the USERNAME parameter is specified, any existing permissions to that username are replaced, otherwise any general permissions are replaced = R gives permission to read data at the user object = W gives permission to change data at the user object = F as W, plus permission to delete the user object = X the access permissions are removed = Z no access allowed	Null, meaning no change

Keyword

Meaning

Default

NAME

Specifies the name of the user_object

= user_object_name
This is of the form *localname, primary_name or primary_name(secondary_name)

*, meaning the current active user_object

ACCESS

Specifies the access permissions to be given. If the USERNAME parameter is specified, any existing permissions to that username are replaced, otherwise any general permissions are replaced

= R
gives permission to read data at the user object

= W
gives permission to change data at the user object

= F
as W, plus permission to delete the user object

= X
the access permissions are removed

= Z
no access allowed

Null, meaning no change

Examples

CHANGE_USER_OBJECT_PERMISSIONS(NAME=*UO,
                               ACCESS=R)

gives all users read access to the user object identified by the localname UO.

CHANGE_USER_OBJECT_PERMISSIONS(NAME=*UO,
                               ACCESS=W,
                               USERNAME=:SYSMAN)

gives :SYSMAN write permission to the user object identified by the local UO, which must have been made permanent before the call.

4.2 CHANGE_USER_OBJECT_ALIAS(CUOAL)

This command creates, replaces or deletes an alias to a user object.

CHANGE_USER_OBJECT_ALIAS(
@ literal @	NAME	= @ mandatory @,
@ literal @	NEW_NAME	= ,
@ literal @	MODE	= R,
.....
@ response @	RESPONSE	= RESULT)

Keyword

Meaning

Default

NAME

Specifies the name of the user object

= user_object_name
Of the form *local_name, primary_name or primary_name(secondary_name)

None, the parameter is mandatory

NEW_NAME

Specifies the new name to be given to the user object. The name must be alphanumeric starting with an alphabetic, i.e. a qualifier is not allowed.

The parameter is ignored if the alias is to be deleted, i.e. MODE = X

= alias_name
The name required for the alias

The parameter is mandatory, unless MODE = X

MODE

Specifies the action required

= N
The NEW_NAME is added as an alias

= R
NAME is changed to NEW_NAME unless NAME is the control name of a file not directly owned by the user. In this case NEW_NAME is added as an alias (replacing an existing alias if one exists)

Note: If the control name of a file is changed, then any existing FMS copies of the file under its original name can be restored through RETRIEVE_FILE only if the original name is reinstated. For this reason, it may be desirable to preserve the file again, this time under the new name

= X
The specified alias name is deleted

Examples

CHANGE_USER_OBJECT_ALIAS(NAME=:USER.WORKPOOL(FILESET),
                         NEW_NAME=WPOOL,
                         MODE=N)

allows the current username to access the user object :USER.WORKPOOL(FILESET) using the name WPOOL.

CHANGE_USER_OBJECT_ALIAS(NAME=:DATASET.INFO(PERMANENT),
                         NEW_NAME=INFOP)

will replace, by INFOP, the alias which exists under the current username to the user object :DATASET.INFO(PERMANENT). If no alias exists, a new alias will be created. This form of the command is particularly useful for renaming the system generated alias named:

ICL9NALIAS<date and time>

created when a specific privacy relationship is introduced.

CHANGE_USER_OBJECT_ALIAS(NAME=POOL,
                         MODE=X)

deletes the alias POOL.

4.3 DISPLAY_USER_OBJECT_DETAILS(DUOD)

This command displays details of a user object. This includes the data stored in the user object and its privacy details.

DISPLAY_USER_OBJECT_DETAILS(
@ literal @	NAME	= @ mandatory @,
@ superliteral @	COMPONENTS	= BASIC,
@ superliteral @	LEVEL	= MIN,
@ int @	START_FROM	= 1,
@ int @	STOP_AFTER	= 255,
@ superliteral @	LIST_TO	= STDI&STDJ,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory
COMPONENTS	Specifies the items to be displayed. One or more values may be supplied separated by &'s = BASIC the BASIC set of data in the user object is output in tabular form = UDATA the UDATA set of data in the user object is output in tabular form = PRIV privacy details about the user object are output The details output depend on the LEVEL parameter	BASIC
LEVEL	Specifies the amount of information output when COMPONENTS=PRIV = MIN gives the general permissions and the caller's permissions to the user object = STD MIN plus a list of the specific permissions to the user object = FULL the same as STD	MIN
START_FROM	Identifies the first item to be displayed when COMPONENTS contains BASIC or UDATA = 1 to 254 the item number from which the output should start	1, the first item
STOP_AFTER	Identifies the last item to be displayed when the COMPONENTS parameter contains BASIC or UDATA = 1 to 255 the item number after which no output is required	255, the last item
LIST_TO	Identifies the destination or destinations of the output. STDI and STDJ can be used in combination with one other parameter value = STDI output to the terminal when called from MAC = STDJ output to the job journal, if one exists = STDLP output to a separate spool file = filename if this is localname then append to the file; if this is a full hierarchic filename, then create a new generation to receive the output. (in either case the file will be temporary)	STDI & STDJ

Examples

DISPLAY_USER_OBJECT_DETAILS(NAME=*UO, COMPONENTS=UDATA)

displays all the data in the UDATA set of the user object identified by *UO in a tabular form. The output is to the job journal, if any, and the MAC terminal in an interactive session.

DISPLAY_USER_OBJECT_DETAILS(NAME=*HK,
                            START_FROM=2,
                            STOP_AFTER=2,
                            LIST_TO=*STDI)

displays to the interactive terminal item number 2 of BASIC data held in the user object selected with local name HK.

4.4 DISPLAY_USER_DETAILS(DUD)

This command displays details of the objects catalogued under the current username. Items of interest are indicated using the COMPONENTS parameter, and the amount of detail required is specified using the LEVEL parameter.

DISPLAY_USER_DETAILS(
@ superliteral @	COMPONENTS	= F&LB,
@ superliteral @	LEVEL	= MIN&MX,
@ literal @	START_FROM	= ,
@ literal @	STOP_AFTER	= ,
@ superliteral @	LIST_TO	= STDI&STDJ,
@ superliteral @	C_COMPONENTS	= ,
@ superliteral @	C_LEVEL	= ,
.....
@ literal @	ACTION	= ,
@ literal @	ALIAS_LEVEL	= MIN,
@ literal @	NAME	= ,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory
COMPONENTS	Specifies the items to be displayed. One or more values may be supplied separated by &'s = BASIC the BASIC set of data in the user object is output in tabular form = UDATA the UDATA set of data in the user object is output in tabular form = PRIV privacy details about the user object are output The details output depend on the LEVEL parameter	BASIC
LEVEL	Specifies the amount of information output when COMPONENTS=PRIV = MIN gives the general permissions and the caller's permissions to the user object = STD MIN plus a list of the specific permissions to the user object = FULL the same as STD	MIN
START_FROM	Identifies the first item to be displayed when COMPONENTS contains BASIC or UDATA = 1 to 254 the item number from which the output should start	1, the first item
STOP_AFTER	Identifies the last item to be displayed when the COMPONENTS parameter contains BASIC or UDATA = 1 to 255 the item number after which no output is required	255, the last item
LIST_TO	Identifies the destination or destinations of the output. STDI and STDJ can be used in combination with one other parameter value = STDI output to the terminal when called from MAC = STDJ output to the job journal, if one exists = STDLP output to a separate spool file = filename if this is localname then append to the file; if this is a full hierarchic filename, then create a new generation to receive the output. (in either case the file will be temporary)	STDI & STDJ

5. Storing data in user objects

Data can be stored in a user object with SET_USER_OBJECT_DETAILS one item at a time, or several items at a time, provided all the items are in the same set (i.e. BASIC or UDATA). The value of a single item can be supplied as a string or an integer. If more than one item is to be stored, a 'TRWLD' string must be constructed for each item. TRWLD represents the item's structure:-

T - Type, the item number in 1 byte (range 1 to 254)
R - Read access key, normally 15 in 1 byte
W - Write access key, normally 15 in 1 byte
L - Length in 1 byte (0 to 255)
D - Data in L bytes

A zero value of L indicates that the item is to be deleted.

Repeated calls to update a permanent user object in a short period of time will cause a considerable amount of activity to the catalogue disc, which may degrade system performance.

5.1 SET_USER_OBJECT_DETAILS (STUOD)

This command updates one or more items of data in the user object. Single items of data are updated using the INT_VALUE or STRING_VALUE parameters, more than one can be updated in a single call of the command using the TRWLD parameter.

SET_USER_OBJECT_DETAILS(
@ literal @	NAME	= @ mandatory @,
@ int @	ITEM	= 1,
@ int @	INT_VALUE	= -1,
@ string @	STRING_VALUE	= ,
@ string @	TRWLD	= ,
@ literal @	BASIC_OR_UDATA	= BASIC,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory
ITEM	Identifies the data item within the user object to be updated = 1 to 254 the given item will be updated with the value of the INT_VALUE or STRING_VALUE parameter = 255 when BASIC_OR_UDATA=UDATA any currently unused item will be updated with the value given in the INT_VALUE or STRING_VALUE parameter = 0 the items are defined by the TRWLD parameter	1
INT_VALUE	Specifies an integer value to be associated with an item in the user object. The parameter is ignored if a value is supplied for the STRING_VALUE parameter or if ITEM=0. If character data or an integer held in other than 8 bytes is to be stored, or if an item is to be deleted, the STRING_VALUE parameter should be used = integer_value which may be a literal, variable name or an SCL integer expression	-1
STRING_VALUE	Specifies the data to be associated with a single item in a user object. A zero length string (e.g. "") causes the item to be deleted. The parameter is ignored if ITEM=0 = string_expression of length 1 to 255 bytes = zero length string the item is to be deleted	If ITEM=0, the TRWLD parameter is used, otherwise the INT_VALUE parameter is used
TRWLD	Specifies a number of different items to be updated in the user object. The ITEM parameter must be set to 0 if this parameter is supplied. Each item to be changed is represented by a TRWLD element, typically of the form HEX(tt0F0Fll) + "d", where: tt is the item number in hexadecimal (01 to FE) ll is the length of data (00 to FF); 00 means delete the item d is the data string of length ll bytes = string_expression a concatenation of TRWLD elements	Mandatory if ITEM = 0, otherwise must be defaulted
BASIC_OR_UDATA	Indicates whether the BASIC or UDATA set of data is being updated. Only the first letter of the value supplied is significant = BASIC the BASIC set of data is to be updated = UDATA the UDATA set of data is to be updated	BASIC

Examples

SET_USER_OBJECT_DETAILS(NAME=*UO,
                        ITEM=47,
                        STRING_VALUE="ITEM 47")

updates the BASIC set of data in the user object identified by *UO. Item 47 is set to the string "ITEM 47".

STRING DATA := HEX(0A0F0F07) + "ITEM 10" + HEX(020F0F00)

SET_USER_OBJECT_DETAILS(NAME=*UO,
                        ITEM=0,
                        TRWLD=DATA,
                        BASIC_OR_UDATA=UDATA)

updates item 10 in the UDATA set of the user object identified by *UO with the string "ITEM 10", and removes the value in item 2 of UDATA.

SET_USER_OBJECT_DETAILS(NAME=*UO,
                        INT_VALUE=2000)

sets the value 2000 in item number 1 of the BASIC data for the user object identified by *UO.

6. Reading data from user objects

Data may be read from a user object either taking all the items in a set (BASIC or UDATA) as a single unit, or as individual items. In either case the data may be output to the job journal and/or MAC terminal, or read into SCL variables.

One item, all items, or a range of items can be listed using the command DISPLAY_USER_OBJECT_DETAILS. The command GIVE_USER_OBJECT_DETAILS can also be used to display the items in a user object, but its main function is to write the value of an item or items to an SCL variable.

Items are normally returned in TRWLD format, that is:

T - Type number of the item in the first byte
R - Read access key, normally 15, in the second byte
W - Write access key, normally 15, in the third byte
L - Length of data, in the fourth byte
D - Data in the fifth and subsequent bytes, in a total of 'length' bytes

6.1 DISPLAY_USER_OBJECT_DETAILS (DUOD)

This command displays details of a user object. This includes the data stored in the user object and its privacy details.

DISPLAY_USER_OBJECT_DETAILS(
@ literal @	NAME	= @ mandatory @,
@ superliteral @	COMPONENTS	= BASIC,
@ superliteral @	LEVEL	= MIN,
@ int @	START_FROM	= 1,
@ int @	STOP_AFTER	= 255,
@ superliteral @	LIST_TO	= STDI&STDJ,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory
COMPONENTS	Specifies the items to be displayed. One or more values may be supplied separated by &'s = BASIC the BASIC set of data in the user object is output in tabular form = UDATA the UDATA set of data in the user object is output in tabular form = PRIV privacy details about the user object are output The details output depend on the LEVEL parameter	BASIC
LEVEL	Specifies the amount of information output when COMPONENTS=PRIV = MIN gives the general permissions and the caller's permissions to the user object = STD MIN plus a list of the specific permissions to the user object = FULL the same as STD	MIN
START_FROM	Identifies the first item to be displayed when COMPONENTS contains BASIC or UDATA = 1 to 254 the item number from which the output should start	1, the first item
STOP_AFTER	Identifies the last item to be displayed when the COMPONENTS parameter contains BASIC or UDATA = 1 to 255 the item number after which no output is required	255, the last item
LIST_TO	Identifies the destination or destinations of the output. STDI and STDJ can be used in combination with one other parameter value. = STDI output to the terminal when called from MAC = STDJ output to the job journal, if one exists = STDLP output to a separate spool file = filename if this is localname then append to the file; if this is a full hierarchic filename then create a new generation to receive the output (in either case the file will be temporary)	STDI & STDJ

Examples

DISPLAY_USER_OBJECT_DETAILS(NAME=*UO,
                            COMPONENTS=UDATA)

displays all the data in the UDATA set of the user object identified by *UO in a tabular form. The output is to the job journal, if any, and the MAC terminal in an interactive session.

DISPLAY_USER_OBJECT_DETAILS(NAME=*HK,
                            START_FROM=2,
                            STOP_AFTER=2,
                            LIST_TO=*STDI)

displays to the interactive terminal item number 2 of BASIC data held in the user object selected with local name HK.

6.2 GIVE_USER_OBJECT_DETAILS (GUOD)

This command may be used to obtain one or all the items of data stored in either the BASIC or UDATA sets in a user object.

GIVE_USER_OBJECT_DETAILS(
@ literal @	NAME	= @ mandatory @,
@ int @	ITEM	= 1,
@ ref int @	INT_VALUE	= ,
@ ref string @	STRING_VALUE	= ,
@ ref int @	LENGTH_OF_STRING	= ,
@ literal @	BASIC_OR_UDATA	= BASIC,
@ response @	RESPONSE	= RESULT)

Keyword	Meaning	Default
NAME	Specifies the name of the user object = user_object_name Of the form *local_name, primary_name or primary_name(secondary_name)	None, the parameter is mandatory
ITEM	Indicates the particular data item to be read, or that all the items in the given set (BASIC or UDATA) are to be read = 1 to 254 identifies the item whose value is required = 0 all the items in the set are returned	1
INT_VALUE	Identifies an SCL variable which will receive the data read from the user object, provided the length of data is eight bytes or less. If no variable of the given name exists, one will be created of mode INT for the duration of the current SCL block. If the data held in the user object item is not an integer, or if ITEM=0, the STRING_VALUE parameter should be used = integer variable the name of an SCL variable of mode INT, which need not already exist	The STRING_VALUE parameter is used, if supplied, otherwise the value is output to the job journal and MAC terminal
STRING_VALUE	Identifies a string variable which will receive the data read from the user object. This parameter will be used if INT_VALUE is defaulted, or the length of data is longer than 8 bytes. If ITEM=0 (ie all items returned), the data is returned in TRWLD format, otherwise just the data field is returned. If no variable of the given name exists, one will be created of mode STRING for the duration of the current SCL block. = string variable the name of an SCL variable of mode STRING, which need not already exist	The INT_VALUE parameter is used, if supplied, otherwise the value is output to the job journal and MAC terminal
LENGTH_OF_STRING	Specifies the name of an SCL integer which is to receive the number of bytes of data read from the user object. If no variable of the given name exists, one will be created for the duration of the current SCL block. The parameter is only updated when a value is returned in the STRING_VALUE parameter = integer variable the name of an SCL variable of mode INT, which need not already exist	No length is returned
BASIC_OR_UDATA	Indicates whether the BASIC or UDATA set is to be obtained. Only the first letter of the value supplied is significant for this parameter = BASIC the BASIC set of data is to be read = UDATA the UDATA set of data is to be read	BASIC

Examples

GIVE_USER_OBJECT_DETAILS(NAME=*UO,
                         BASIC_OR_UDATA=UDATA)

outputs the contents of the first item in the UDATA set of the user object identified by *UO to the job journal and MAC terminal, if any.

STRING (1500) OUTDATA

INT OUTLENGTH

GIVE_USER_OBJECT_DETAILS(NAME=*UO,
                         ITEM=0,
                         STRING_VALUE=OUTDATA,
                         LENGTH_OF_STRING=OUTLENGTH)

outputs the whole of the data in the BASIC set of the user object identified by *UO to the string OUTDATA. The length of the data written is returned in OUTLENGTH.

7. Copying user objects

As an example of the way user objects are manipulated, the SCL statements below illustrate how the data in one user object can be copied to a second user object.

After creation of the second user object, the data is transferred via an SCL variable BUFFER. The BASIC and UDATA parts are transferred separately. Finally the copy is made permanent.

STRING BUFFER

SELECT_USER_OBJECT(NAME=MASTERUO,
                   LNAME=MASTER)

CREATE_USER_OBJECT(NAME=COPYUO,
                   LNAME=COPY)

GIVE_USER_OBJECT_DETAILS(NAME=*MASTER,
                         ITEM=0,
                         STRING_VALUE=BUFFER)

SET_USER_OBJECT_DETAILS(NAME=*COPY,
                        ITEM=0,
                        TRWLD=BUFFER)

GIVE_USER_OBJECT_DETAILS(NAME=*MASTER,
                         ITEM=0,
                         STRING_VALUE=BUFFER,
                         BASIC_OR_UDATA=UDATA)

SET_USER_OBJECT_DETAILS(NAME=*COPY,
                        ITEM=0,
                        TRWLD=BUFFER,
                        BASIC_OR_UDATA=UDATA)

SAVE_USER_OBJECT(NAME=*COPY)

VME stuff index