1 – SCA$ASYNCH_TERMINATE
Sets a flag indicating that a CTRL-C has been issued. Format SCA$ASYNCH_TERMINATE command_context
1.1 – Argument
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference SCA command context value.
1.2 – Condition Value Returned
SCA$_NORMAL Normal successful completion.
1.3 – Description
The SCA$ASYNCH_TERMINATE routine sets a flag indicating that a CTRL-C has been issued.
2 – SCA$CLEANUP
Shuts down the SCA callable command interface, freeing all dynamic memory associated with the interface routines and data structures. Format SCA$CLEANUP command_context
2.1 – Argument
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context value.
2.2 – Condition Value Returned
SCA$_NORMAL The SCA callable command interface has been successfully shut down.
2.3 – Description
The SCA$CLEANUP routine shuts down the SCA callable command interface, freeing all dynamic memory associated with the interface routines and data structures.
3 – SCA$DO_COMMAND
Parses an SCA subsystem command and invokes command processing if the command is syntactically correct. Format SCA$DO_COMMAND command_context, command_string [,parameter_routine] [,continuation_routine] [,continuation_prompt] [,user_argument] [,confirm_routine] [,topic_routine] [,display_routine]
3.1 – Arguments
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference SCA command context value. command_string type: character string access: read only mechanism: by descriptor An SCA subsystem command. parameter_routine type: procedure access: read only mechanism: by reference Routine that prompts for required parameters. You can specify LIB$GET_INPUT or a compatible routine. If a routine address of zero (0) is specified, commands with missing parameters fail and display a CLI error message. continuation_routine type: procedure access: read only mechanism: by reference Routine that prompts for the remainder of a continued command (i.e., a command that ends with a hyphen). You can specify LIB$GET_INPUT or a compatible routine. continuation_prompt type: character string access: read only mechanism: by descriptor Command continuation prompt string (e.g., SCA> ). user_argument type: longword access: read only mechanism: by reference User-specified value to be passed to any action routine (other than CLI prompt routines) called by this routine. confirm_routine type: procedure access: read only mechanism: by value Command confirmation prompt routine to be used by commands that support a /CONFIRM qualifier. You can specify SCA$GET_INPUT or a compatible routine. If this argument is omitted, the /CONFIRM qualifier is not supported. topic_routine type: procedure access: read only mechanism: by value Help topic prompt routine. You can specify LIB$GET_INPUT or a compatible routine. If this routine returns an error, command processing is terminated. If this argument is omitted, no help prompting is performed. display_routine type: procedure access: read only mechanism: by value Routine to be called to display one line of command output. You can specify SCA$PUT_OUTPUT or a compatible routine. If this routine returns an error, command processing is terminated. If this argument is omitted, no display routine is called.
3.2 – Condition Values Returned
All SCA condition values and many system values.
3.3 – Description
The SCA$DO_COMMAND routine parses an SCA subsystem command and invokes command processing if the command is syntactically correct.
4 – SCA$GET_ATTRIBUTE
Gets a handle to an attribute of an entity. Format SCA$GET_ATTRIBUTE entity, attribute_kind, attribute_handle, [,iteration_context]
4.1 – Arguments
entity type: $SCA_HANDLE access: read only mechanism: by reference An SCA entity handle describing the entity or relationship whose attributes are being obtained. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read only mechanism: by reference The kind of attribute to be obtained. Any attribute-kind can be specified on this routine. attribute_handle type: $SCA_HANDLE access: write only mechanism: by reference An SCA attribute handle that is to describe the obtained attribute. iteration_context type: $SCA_ITERATION_CONTEXT access: read/write mechanism: by reference Optional. The iteration-context. This longword must contain zero on the first call to this routine for a particular iteration. This routine uses the longword to maintain the iteration context. The caller must not change the contents of the longword.
4.2 – Condition Values Returned
SCA$_NORMAL An attribute has been successfully returned. SCA$_NONE Warning. An attribute has not been returned. Either there are no such attributes at all in the entity or there are no more attributes.
4.3 – Description
The SCA$GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter.
5 – SCA$GET_ATTRI_KIND_T
Gets an attribute kind. Format SCA$GET_ATTRI_KIND_T attribute_handle, attribute_kind
5.1 – Arguments
attribute_handle type: $SCA_HANDLE access: read only mechanism: by reference An SCA handle describing an attribute whose attribute-kind is to be obtained. attribute_kind type: character string access: write only mechanism: by descriptor The kind of the attribute.
5.2 – Condition Value Returned
SCA$_NORMAL An attribute kind has been successfully returned.
5.3 – Description
The SCA$GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string.
6 – SCA$GET_ATTRI_VALUE_T
Gets an attribute value. Format SCA$GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind]
6.1 – Arguments
handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA attribute handle describing either an attribute or an entity whose value is to be obtained. attribute_value type: character string access: read/write mechanism: by descriptor The (string) value of the attribute being selected. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read/write mechanism: by reference Optional. The kind of attribute to be obtained.
6.2 – Condition Values Returned
SCA$_NORMAL An attribute value has been successfully returned. SCA$_NONE Warning. An attibute-value has not been returned. There are no such attributes in the entity. This condition can be returned only if this routine is processing an entity.
6.3 – Description
The SCA$GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$GET_ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind.
7 – SCA$GET_CURRENT_QUERY
Gets the name of the current query in the given command context. Format SCA$GET_CURRENT_QUERY command_context, query_name
7.1 – Arguments
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_name type: character string access: write only mechanism: by descriptor The name of the current query in the context of the given command context.
7.2 – Condition Values Returned
SCA$_NORMAL The name of the current query has been successfully retrieved.
7.3 – Description
The SCA$GET_CURRENT_QUERY routine gets the name of the current query in the given command context.
8 – SCA$GET_INPUT
Gets one record of ASCII text from the current controlling input device specified by SYS$INPUT. Format SCA$GET_INPUT get_string, [,prompt_string] [,output_length] [,user_argument]
8.1 – Arguments
get_string type: character string access: write only mechanism: by descriptor Buffer to receive the line read from SYS$INPUT. The string is returned by a call to STR$COPY_DX. prompt_string type: character string access: read only mechanism: by descriptor Prompt message that is displayed on the controlling terminal. A valid prompt consists of text followed by a colon (:), a space, and no carriage-return/line-feed combination. The maximum size of the prompt message is 255 characters. If the controlling input device is not a terminal, this argument is ignored. output_length type: word access: write only mechanism: by reference Word to receive the actual length of the GET-STRING line, not counting any padding in the case of a fixed string. If the input line was truncated, this length reflects the truncated string. user_argument type: _UNSPECIFIED access: read only mechanism: by reference User-specified value that was passed to the routine that called this action routine.
8.2 – Condition Values Returned
SCA$_NORMAL An input line was returned. Failure completion code from LIB$GET_ INPUT.
8.3 – Description
The SCA$GET_INPUT routine gets one record of ASCII text from the current controlling input device specified by SYS$INPUT.
9 – SCA$GET_OCCURRENCE
Returns an occurrence from the query specified by the query_name argument. Format SCA$GET_OCCURRENCE command_context, query_name, occurrence
9.1 – Arguments
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_name type: character string access: read only mechanism: by descriptor The name of the query in the context of the command context. occurrence type: $SCA_HANDLE access: read/write mechanism: by reference An SCA occurrence handle that describes an occurrence.
9.2 – Condition Values Returned
SCA$_NORMAL An occurrence has been successfully returned. SCA$_NEWNAME An occurrence has been successfully returned. This occurrence has a different name from the occurrence that was returned by the previous call to this routine with this query context. This condition implies that this new occurrence is also of a different symbol. SCA$_NEWITEM An occurrence has been successfully returned. This new occurrence is of a different symbol from the occurrence that was returned by the previous call to this routine with this query context. SCA$_NOMORE Warning. An occurrence has not been returned. The traversal of the query result has been exhausted.
9.3 – Description
The SCA$GET_OCCURRENCE routine returns an occurrence from the query specified by the query_name argument. If the occurrence handle supplied is zero, the routine returns a handle to the first occurrence in the query represented by the argument query_name. If the occurrence handle supplied on input represents a valid occurrence, the routine returns a handle to the next occurrence in the query result. In order to be valid, the occurrence handle supplied on input must refer to an occurrence in the query represented by the argument query_name. The query name supplied is interpreted in the context of the command context identified by the argument command_context. Note that the order of retrieval of the occurrences is undefined.
10 – SCA$INITIALIZE
Initializes the SCA callable command interface. Format SCA$INITIALIZE command_context
10.1 – Argument
command_context type: $SCA_COMMAND_CONTEXT access: write only mechanism: by reference SCA command context value to be initialized. This value is passed as an argument to other SCA$xxx routines.
10.2 – Condition Value Returned
SCA$_NORMAL The SCA callable command interface has been successfully initialized.
10.3 – Description
The SCA$INITIALIZE routine initializes the SCA callable command interface.
11 – SCA$LOCK_LIBRARY
Locks all the physical libraries in the current virtual library list so that they cannot be modified. Format SCA$LOCK_LIBRARY command_context
11.1 – Argument
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context.
11.2 – Condition Value Returned
SCA$_NORMAL The libraries have been successfully locked.
11.3 – Description
The SCA$LOCK_LIBRARY routine locks all the physical libraries in the current virtual library list so that they cannot be modified.
12 – SCA$PUT_OUTPUT
Writes a record to the current controlling output device specified by SYS$OUTPUT. Format SCA$PUT_OUTPUT string, user_argument
12.1 – Arguments
string type: character string access: read only mechanism: by descriptor String to be written to SYS$OUTPUT. You can concatenate one or more additional character strings with the primary string to form a single output record. You can specify a maximum of 20 strings. The maximum resulting record length is 255 characters. user_argument type: _UNSPECIFIED access: read only mechanism: by reference User-specified value that was passed to the routine that called this action routine.
12.2 – Condition Values Returned
SCA$_NORMAL The string was successfully written to SYS$OUTPUT. Failure completion code from the VAX RMS $PUT service.
12.3 – Description
The SCA$PUT_OUTPUT routine writes a record to the current controlling output device specified by SYS$OUTPUT.
13 – SCA$QUERY_CLEANUP
Cleans up an SCA query context, freeing all dynamic memory associated with the query. Format SCA$QUERY_CLEANUP query_context
13.1 – Argument
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context to be cleaned up.
13.2 – Condition Value Returned
SCA$_NORMAL The query context has been successfully cleaned up.
13.3 – Description
The SCA$QUERY_CLEANUP routine cleans up an SCA query context, freeing all dynamic memory associated with the query. This routine will become obsolete in a future version of SCA.
14 – SCA$QUERY_COPY
Copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. Format SCA$QUERY_COPY src_query_context, dst_query_context
14.1 – Arguments
src_query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that describes the query to be copied. dst_query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context into which the query is to be copied.
14.2 – Condition Value Returned
SCA$_NORMAL The query expression has been successfully copied.
14.3 – Description
The SCA$QUERY_COPY routine copies a query from SRC_QUERY_CONTEXT to DST_QUERY_CONTEXT. This will copy whatever is in SRC_QUERY_ CONTEXT, whether that is a question, or a question and a result. This routine will become obsolete in a future version of SCA.
15 – SCA$QUERY_FIND
Finds the occurrences that match the query expression specified by QUERY_CONTEXT. Format SCA$QUERY_FIND query_context
15.1 – Argument
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that describes a query expression to be evaluated.
15.2 – Condition Values Returned
SCA$_NORMAL The query expression has been successfully evaluated. SCA$_NOOCCUR No occurrences match the query expression. SCA$_RESULTEXISTS The query already has a result prior to this call.
15.3 – Description
The SCA$QUERY_FIND routine finds the occurrences that match the query expression specified by QUERY_CONTEXT. This routine will become obsolete in a future version of SCA.
16 – SCA$QUERY_GET_ATTRIBUTE
Gets a handle to an attribute of an entity. Format SCA$QUERY_GET_ATTRIBUTE entity, attribute_kind, attribute_handle, [,iteration_context]
16.1 – Arguments
entity type: $SCA_HANDLE access: read only mechanism: by reference An SCA entity handle describing the entity or relationship whose attributes are being obtained. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read only mechanism: by reference The kind of attribute to be obtained. Any attribute-kind can be specified on this routine. attribute_handle type: $SCA_HANDLE access: write only mechanism: by reference An SCA attribute handle that is to describe the obtained attribute. iteration_context type: $SCA_ITERATION_CONTEXT access: read/write mechanism: by reference Optional. The iteration-context. This longword must contain zero on the first call to this routine for a particular iteration. This routine uses the longword to maintain the iteration context. The caller must not change the contents of the longword.
16.2 – Condition Values Returned
SCA$_NORMAL An attribute has been successfully returned. SCA$_NONE Warning. An attribute has not been returned. Either there are no such attributes at all in the entity or there are no more attributes.
16.3 – Description
The SCA$QUERY_GET_ATTRIBUTE routine gets a handle to an attribute of an entity. If the iteration_context parameter is not specified, then this routine finds the first attribute of the specified kind (attribute_kind) and updates attribute_handle to describe that attribute. In general, several attributes can be associated with a particular entity. With this routine you can find all of those attributes by using the iteration_context parameter. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRIBUTE routine supersedes this routine.
17 – SCA$QUERY_GET_ATTRI_KIND_T
Gets an attribute kind. Format SCA$QUERY_GET_ATTRI_KIND_T attribute_handle, attribute_kind
17.1 – Arguments
attribute_handle type: $SCA_HANDLE access: read only mechanism: by reference An SCA handle describing an attribute whose attribute-kind is to be obtained. attribute_kind type: character string access: write only mechanism: by descriptor The kind of the attribute.
17.2 – Condition Value Returned
SCA$_NORMAL An attribute kind has been successfully returned.
17.3 – Description
The SCA$QUERY_GET_ATTRI_KIND_T routine returns the kind of any attribute as a character string. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_KIND_T routine supersedes this routine.
18 – SCA$QUERY_GET_ATTRI_VALUE_T
Gets an attribute value. Format SCA$QUERY_GET_ATTRI_VALUE_T handle, attribute_value [,attribute_kind]
18.1 – Arguments
handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA attribute handle describing either an attribute or an entity whose value is to be obtained. attribute_value type: character string access: read/write mechanism: by descriptor The (string) value of the attribute being selected. attribute_kind type: $SCA_ATTRIBUTE_KIND access: read/write mechanism: by reference Optional. The kind of attribute to be obtained.
18.2 – Condition Values Returned
SCA$_NORMAL An attribute value has been successfully returned. SCA$_NONE Warning. An attibute-value has not been returned. There are no such attributes in the entity. This condition can be returned only if this routine is processing an entity.
18.3 – Description
The SCA$QUERY_GET_ATTRI_VALUE_T routine returns the value of any attribute as a character string. If the handle describes an attribute, then this routine returns the value of that attribute. In this case, the attribute_kind parameter must not be specified. If the handle describes an entity, then this routine returns the value of the first attribute of that entity that is of the kind specified by the attribute_kind parameter. In this case, the attribute_kind parameter must be specified. If you want to get more than one attribute value of a particular kind for an entity, you must use the routine SCA$QUERY_GET_ ATTRIBUTE. This applies only to the attribute kinds SCA$K_ATTRI_ NAME and SCA$K_ATTRI_ALL. The value of any kind of attribute can be returned by this routine, except for SCA$K_ATTRI_ALL. This routine will convert to character string those attributes whose data type is not character string. This routine does not accept the attribute-kind SCA$K_ATTRI_ALL as the value of the attribute_kind parameter. It is not meaningful to get just the first attribute without regard to attribute-kind. This routine will become obsolete in a future version of SCA. The SCA$GET_ATTRI_VALUE_T routine supersedes this routine.
19 – SCA$QUERY_GET_NAME
Returns the name of a query. Format SCA$QUERY_GET_NAME query_context, query_name
19.1 – Arguments
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context whose name is to be obtained. query_name type: character string access: write only mechanism: by descriptor The name of the query.
19.2 – Condition Value Returned
SCA$_NORMAL The query name has been successfully returned.
19.3 – Description
The SCA$QUERY_GET_NAME routine returns the name of a query. This routine will become obsolete in a future version of SCA.
20 – SCA$QUERY_GET_OCCURRENCE
Gets the next occurrence in the query result that is specified as a query_context argument. Format SCA$QUERY_GET_OCCURRENCE query_context, entity_handle
20.1 – Arguments
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context whose occurrences are to be obtained. entity_handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA entity handle that describes an entity.
20.2 – Condition Values Returned
SCA$_NORMAL An occurrence has been successfully returned. SCA$_NEWSYMBOL An occurrence has been successfully returned. This new occurrence is of a different symbol than the occurrence that was returned by the previous call to this routine. SCA$_NOMORE Warning. An occurrence has not been returned. The traversal of the query result has been exhausted.
20.3 – Description
The SCA$QUERY_GET_OCCURRENCE routine successively returns every occurrence in a query result. It provides one pass through all of the occurrences. This routine will become obsolete in a future version of SCA. The SCA$GET_OCCURRENCE routine supersedes this routine.
21 – SCA$QUERY_INITIALIZE
Initializes an SCA query context. Format SCA$QUERY_INITIALIZE command_context, query_context
21.1 – Arguments
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context. query_context type: $SCA_QUERY_CONTEXT access: write only mechanism: by reference An SCA query context to be initialized. This value is passed as an argument to other SCA query routines (SCA$QUERY_xxx).
21.2 – Condition Value Returned
SCA$_NORMAL The query context has been successfully initialized.
21.3 – Description
The SCA$QUERY_INITIALIZE routine initializes an SCA query context. This routine must be called before any other SCA$QUERY_ routines. This routine will become obsolete in a future version of SCA.
22 – SCA$QUERY_PARSE
Parses a query expression command string and sets up a query context if the command is syntactically correct. Format SCA$QUERY_PARSE query_context, query_expression_string [,query_expression_length]
22.1 – Arguments
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that is to describe the indicated query expression. query_expression_string type: character string access: read only mechanism: by descriptor A query expression string. query_expression_length type: longword access: write only mechanism: by reference Optional. Length of the query expression, returned from the parser.
22.2 – Condition Values Returned
SCA$_NORMAL The query expression string has been successfully parsed. SCA$_MORETEXT Warning. The query expression string has been successfully parsed, but the text following the query expression is not a legal part of the query expression. This condition is returned only if the query_ expression_length parameter is specified. If the query_expression_length parmeter is not specified, then this routine insists that the whole query_expression_string argument be a legal query expression; in this case all errors are signaled.
22.3 – Description
The SCA$QUERY_PARSE routine parses a query expression string and sets up a query context if the command is syntactically correct. This routine will become obsolete in a future version of SCA.
23 – SCA$QUERY_SELECT_OCCURRENCE
Creates a query expression that matches a specific entity. Format SCA$QUERY_SELECT_OCCURRENCE query_context, entity_handle
23.1 – Arguments
query_context type: $SCA_QUERY_CONTEXT access: read/write mechanism: by reference An SCA query context that is to describe a specific entity. entity_handle type: $SCA_HANDLE access: read/write mechanism: by reference An SCA entity handle that describes the entity that the newly defined query context is to match.
23.2 – Condition Value Returned
SCA$_NORMAL A query expression has been successfully defined.
23.3 – Description
The SCA$QUERY_SELECT_OCCURRENCE routine creates a query expression that matches a specific entity. You use this routine to specify queries based on the results of previous queries. The entity_handle parameter is obtained by traversing the results of a previous query evaluation. Typically, the query context of the entity_handle parameter is not the same as the query_context parameter. However, they can be the same. If they are the same query context, then that previous query is replaced with the query defined by this routine and, as a result, entity_handle becomes invalid. This routine will become obsolete in a future version of SCA. The SCA$SELECT_OCCURRENCE routine supersedes this routine.
24 – SCA$SELECT_OCCURRENCE
Creates a query that matches a specific occurrence. Format SCA$SELECT_OCCURRENCE occurrence, query_name
24.1 – Arguments
occurrence type: $SCA_HANDLE access: read only mechanism: by reference An SCA occurrence handle which describes the occurrence that the newly created query is to match. query_name type: character string access: write only mechanism: by descriptor The name of the newly created query. This query is created in the context of the same command context as that in which the input occurrence handle is defined.
24.2 – Condition Values Returned
SCA$_NORMAL A query expression has been successfully defined.
24.3 – Description
You use this routine to create new queries based on the results of previous queries. The occurrence handle parameter is obtained by traversing the results of a previous query evaluation.
25 – SCA$UNLOCK_LIBRARY
Unlocks all the physical libraries in the current virtual library list so that they can be modified. Format SCA$UNLOCK_LIBRARY command_context
25.1 – Argument
command_context type: $SCA_COMMAND_CONTEXT access: read/write mechanism: by reference An SCA command context.
25.2 – Condition Value Returned
SCA$_NORMAL The libraries have been successfully unlocked.
25.3 – Description
The SCA$UNLOCK_LIBRARY routine unlocks all the physical libraries in the current virtual library list so that they can be modified.