HELPLIB.HLB  —  SCA  SCA Topics, Callable Routines

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
    from the 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.
Close Help