VMS Help SMB Routines, SMB$INITIALIZE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The SMB$INITIALIZE routine initializes the user-written symbiont
    and the interface between the symbiont and the job controller. It
    allocates and initializes the internal databases of the interface
    and sets up the mechanism that is to wake up the symbiont when a
    message is received.

    Format

      SMB$INITIALIZE  structure_level [,ast_routine] [,streams]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 structure_level

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Version of the symbiont/job controller interface. The structure_
    level argument is the address of a longword containing the
    version of the symbiont/job controller interface used when the
    symbiont was compiled. Always place the value of the symbol
    SMBMSG$K_STRUCTURE_LEVEL in the longword addressed by this
    argument. Each programming language provides an appropriate
    mechanism for defining symbols.

 ast_routine

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       read only
    mechanism:    by reference
    Message-handling routine called at AST level. The ast_routine
    argument is the address of the entry point of the message-
    handling routine to be called at AST level when the symbiont
    receives a message from the job controller. The AST routine is
    called with no parameters and returns no value. If an AST routine
    is specified, the routine is called once each time the symbiont
    receives a message from the job controller.

    The AST routine typically reads the message and determines if
    immediate action must be taken. Be aware that an AST can be
    delivered only while the symbiont is operating at non-AST level.
    Thus, to ensure delivery of messages from the job controller, the
    symbiont should not perform lengthy operations at AST level.

    If you do not specify the ast_routine argument, the symbiont
    must call the SMB$CHECK_FOR_MESSAGE routine to check for waiting
    messages.

 streams

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Maximum number of streams the symbiont is to support. The streams
    argument is the address of a longword containing the number of
    streams that the symbiont is to support. The number must be in
    the range of 1 to 32.

    If you do not specify this argument, a default value of 1 is
    used. Thus, by default, a symbiont supports one stream. Such a
    symbiont is called a single-threaded symbiont.

    A stream (or thread) is a logical link between a queue and a
    symbiont. When a symbiont is linked to more than one queue, and
    serves those queues simultaneously, it is called a multithreaded
    symbiont.

3 - Description

    Your symbiont must call SMB$INITIALIZE before calling any
    other SMB routines. It calls SMB$INITIALIZE in order to do the
    following:

    o  Allocate and initialize the SMB facility's internal database.

    o  Establish the interface between the job controller and the
       symbiont.

    o  Determine the threading scheme of the symbiont.

    o  Set up the mechanism to wake your symbiont when a message is
       received.

    After the symbiont calls SMB$INITIALIZE, it can communicate with
    the job controller using the other SMB routines.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SMB$_INVSTRLEV     Invalid structure level.

    This routine also returns any codes returned by $ASSIGN and
    LIB$GET_VM.