Format

SYS$GETUTC utcadr

C Prototype

int sys$getutc (unsigned int *utcadr [4]);

Arguments

The 128-bit time value to be returned.

Description

The Get UTC Time service returns the current system time in 128-bit UTC format. System time is updated every 10 milliseconds.

On Alpha and Integrity server systems, the frequency at which system time is updated varies, depending on the clock frequency of the Alpha or Integrity servers processor.

Required Access or Privileges

None

Required Quota

None

Related Services

$ASCUTC, $BINUTC, $NUMUTC, $TIMCON

Condition Values Returned

Format

SYS$GET_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size

C Prototype

int sys$get_align_fault_data
   (void *buffer, int buffer_size, int *return_size);

Arguments

The user buffer in which the alignment fault data is to be stored. The buffer is the 32- or 64-bit address of this user buffer.

The size, in bytes, of the buffer specified by the buffer argument.

The amount of data, in bytes, stored in the buffer. The return_size argument is the 32- or 64-bit address of a naturally aligned longword into which the service returns the size of the buffer. The return_size is set to 0 if there is no data in the buffer.

Description

The Get Alignment Fault Data service obtains data from the user image alignment fault buffer if buffered user alignment fault data reporting has been enabled.

When buffered user alignment fault data reporting is enabled, the operating system writes each alignment fault into a user-defined buffer. The user must poll this buffer periodically to read the data.

The user must call the $START_ALIGN_FAULT_REPORT service to enable buffered user alignment fault data reporting.

For more information about buffered user alignment fault data reporting, see the $START_ALIGN_FAULT_REPORT system service.

Required Access or Privileges

None

Required Quota

None

Related Services

$GET_SYS_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

Format

SYS$GET_ARITH_EXCEPTION sigarg ,mcharg ,buffer

C Prototype

int sys$get_arith_exception
   (void *sigarg, void *mcharg, void *buffer);

Arguments

Address of the signal array for the given arithmetic exception.

Address of the mechanism array for the given arithmetic exception.

Four-quadword buffer to receive additional exception context. The buffer argument is the address of a descriptor that points to this buffer.

Description

Required Access or Privilege

None

Required Quota

None

Condition Values Returned

Format

SYS$GET_DEFAULT_TRANS tid

C Prototype

int sys$get_default_trans (unsigned int tid [4]);

Arguments

Address of an octaword in which the identifier (TID) of the default transaction of the calling process is returned.

Description

A precondition for the successful completion of $GET_DEFAULT_TRANS is that the calling process must have a default transaction.

$GET_DEFAULT_TRANS may fail for various reasons, including:

Required Privileges

None

Required Quotas

None

Related Services

$ABORT_TRANS, $ABORT_TRANSW, $ACK_EVENT, $ADD_BRANCH, $ADD_BRANCHW, $CREATE_UID, $DECLARE_RM, $DECLARE_RMW, $END_BRANCH, $END_BRANCHW, $END_TRANS, $END_TRANSW, $FORGET_RM, $FORGET_RMW, $GETDTI, $GETDTIW, $JOIN_RM, $JOIN_RMW, $SETDTI, $SETDTIW, $SET_DEFAULT_TRANS, $SET_DEFAULT_TRANSW, $START_BRANCH, $START_BRANCHW, $START_TRANS, $START_TRANSW, $TRANS_EVENT, $TRANS_EVENTW

Condition Values Returned

Format

SYS$GET_GALAXY_LOCK_INFO
   handle ,name ,timeout ,size ,ipl ,rank ,flags [,name_length]

C Prototype

int sys$get_galaxy_lock_info
   (unsigned __int64 lock_handle, char *name, unsigned int *timeout,
    unsigned int *size, unsigned int *ipl, unsigned int *rank,
    unsigned short int *flags unsigned short int *name_length);

Arguments

The 64-bit lock handle that identifies the lock on which to return information. This value is returned by SYS$CREATE_GALAXY_LOCK.

Pointer to a buffer. This buffer must be large enough to receive the name of the lock. Locks names are zero-terminated strings with a maximum size of 16 bytes.

Pointer to a longword. The value returned is the timeout value of the lock.

Pointer to a longword. The value returned is the size of the lock in bytes.

Pointer to a longword. The value returned is the IPL of the lock.

Pointer to a longword. The value returned is the rank of the lock.

Pointer to a word. The value returned is the word mask of lock flags.

Length of the string returned in the name argument.

Description

This service returns all "interesting" fields from the specified lock. See the $CREATE_GALAXY_LOCK service for detailed information regarding these values.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK

Condition Values Returned

Format

SYS$GET_GALAXY_LOCK_SIZE min_size ,max_size

C Prototype

int sys$get_galaxy_lock_size
   (unsigned int *min_size, unsigned int *max_size);

Arguments

Pointer to a longword. The value returned is minimum legal size of a galaxy lock structure.

Pointer to a longword. The value returned is maximum legal size of a galaxy lock structure.

Description

This service returns the minimum and maximum size of an OpenVMS Galaxy lock. If a lock is created with the maximum size, the locking services will record acquire and release information in the lock.

The lock sizes can be used to determine the value of the section_size parameter to the $CREATE_GALAXY_LOCK_TABLE service.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $RELEASE_GALAXY_LOCK

Condition Values Returned

Format

SYS$GET_REGION_INFO
   function_code ,region_id_64 ,start_va_64 ,nullarg ,buffer_length
   ,buffer_address_64 ,return_length_64

C Prototype

int sys$get_region_info
   (unsigned int function_code, struct _generic_64 *region_id_64,
    void *start_va_64, void *reserved, unsigned int buffer_length,
    void *buffer_address_64, unsigned int *return_length_64);

Arguments

Function code specifying how the information you are requesting should be looked up. All function codes return region summary information in the return buffer in the format of the Region Summary Buffer. The Region Summary Buffer format is shown in Table 2 in the buffer_address_64 argument.

If less buffer space is specified than the length of the Region Summary Buffer, only the amount of information requested is returned. If more buffer space is specified than the length of the Region Summary Buffer, the service will fill in the buffer. The return length will reflect the amount of useful information written to the buffer, the size of the Region Summary Buffer.

The region ID associated with the region about which information is requested. This argument is read only if the function code VA$_REGSUM_BY_ID is specified.

Other region IDs, as returned by the $CREATE_REGION_64 service, can be specified.

Virtual address associated with region about which information is requested. This argument is read only if the function_code argument is VA$_REGSUM_BY_VA or VA$_NEXT_REGSUM_BY_VA.

If the function_code argument is VA$_REGSUM_BY_VA, this argument is a virtual address within the region about which you are requesting information.

Placeholding argument reserved to OpenVMS.

Length of the buffer into which information is returned.

The 32- or 64-bit virtual address of a quadword-aligned buffer into which to return information if the buffer_length argument is non-zero.

The 32- or 64-bit virtual address of a naturally aligned longword into which the service returns the length of the information in bytes.

Description

The Get Information About a Specified Virtual Region service is a kernel mode service that can be called from any mode. This service gets the requested information about the specified region or the next region in a wildcard search. If the returned value of this service is not a successful condition value, a value cannot be returned in the memory locations pointed to by the buffer_address_64 or return_length_64 arguments.

Required Privileges

None

Required Quota

None

Related Services

$CREATE_REGION_64, $DELETE_REGION_64

Condition Values Returned

Format

SYS$GET_SECURITY
   [clsnam] ,[objnam] ,[objhan]  ,[flags] ,[itmlst] ,[contxt] ,[acmode]

C Prototype

int sys$get_security
   (void *clsnam, void *objnam,  unsigned int *objhan, unsigned int flags,
    void *itmlst, unsigned int *contxt,  unsigned int *acmode);

Arguments

Name of the protected object whose associated security profile is going to be retrieved. The objnam argument is the address of a descriptor pointing to a string containing the name of the protected object.

These symbolic names are defined in the $OSSDEF macro. You construct the flags argument by specifying the symbolic names of each flag.

Item list specifying which information about the process or processes is to be returned. The itmlst argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by a longword of 0.

With the item list, the user retrieves the protected object's characteristics. The user defines which security characteristics to retrieve. If this argument is not present, only the flags argument is processed. Without the itmlst argument, you can only manipulate the security profile lock or release contxt resources.

The following diagram depicts a single item descriptor.

Value used to maintain the processing context when dealing with a single protected object across multiple $GET_SECURITY/$SET_SECURITY calls. Whenever the context value is nonzero, the class name, object name, or object handle arguments are disregarded. An input value of 0 indicates that a new context should be established.

Because an active context block consumes process memory, be sure to release the context block by setting the RELCTX flag when the profile processing is complete. $GET_SECURITY sets the context argument to 0 once the context is released.

Access mode to be used in the object protection check. The acmode argument is the address of a longword containing the access mode. The acmode argument defaults to kernel mode; however, the system compares acmode with the caller's access mode and uses the least privileged mode. The access modes are defined in the system macro $PSLDEF library. VSI recommends that this argument be omitted (passed as zero).

Item Codes

The following table provides a summary of item codes that are valid in an item descriptor in the itmlst argument. Complete descriptions of each item code are provided after the table.

OSS$_ACCESS_NAMES

When you specify OSS$_ACCESS_NAMES, $GET_SECURITY returns the access name translation table in the buffer pointed to by the buffer address field of the item descriptor.

The access name translation table is a 32-quadword vector followed by a variable section containing the access names. Each bit in the vector represents a single access type. The contents of the quadword is a string descriptor that corresponds to the ASCII bitname string. Undefined access types have zero-length names. The return length, if present, returns the length of the table.

OSS$_ACCESS_NAMES_LENGTH

When you specify OSS$_ACCESS_NAMES_LENGTH, $GET_SECURITY returns the length of the access name translation table.

OSS$_ACL_FIND_ENTRY

When you specify OSS$_ACL_FIND_ENTRY, $GET_SECURITY locates an ACE pointed to by the buffer address. OSS$_ACL_FIND_ENTRY sets the position within the ACL for succeeding ACL operations; for example, for a deletion or modification of the ACE. If the buffer address is 0, it returns SS$_ACCVIO.

OSS$_ACL_FIND_NEXT

When you specify OSS$_ACL_FIND_NEXT, $GET_SECURITY advances the current position to the next ACE in the ACL.

OSS$_ACL_FIND_TYPE

When you specify OSS$_ACL_FIND_TYPE, $GET_SECURITY returns an ACE of a particular type if there is one in the buffer pointed to by the buffer address. OSS$_ACL_FIND_TYPE sets the position within the ACL for succeeding ACL operations. If the buffer address is 0, it returns SS$_ACCVIO.

OSS$_ACL_GRANT_ACE

When you specify OSS$_ACL_GRANT_ACE, $GET_SECURITY returns the ACE in the object's ACL that grants or denies the user access to that object. OSS$_ACL_GRANT_ACE returns the ACE found in the buffer pointed to by the buffer address.

OSS$_ACL_LENGTH

When you specify OSS$_ACL_LENGTH, $GET_SECURITY returns the size (in bytes) of the object's ACL. The buffer address field points to a longword that receives the size.

OSS$_ACL_POSITION_BOTTOM

When you specify OSS$_ACL_POSITION_BOTTOM, $GET_SECURITY sets the ACL position to point to the bottom of the ACL.

OSS$_ACL_POSITION_TOP

When you specify OSS$_ACL_POSITION_TOP, $GET_SECURITY sets the ACL position to point to the top of the ACL.

OSS$_ACL_READ

When you specify OSS$_ACL_READ, $GET_SECURITY returns the portion of the object's ACL to the buffer pointed to by the buffer address.

OSS$_ACL_READ_ENTRY

When you specify OSS$_ACL_READ_ENTRY, $GET_SECURITY reads the ACE pointed to by the buffer address.

OSS$_CLASS_NAME

When you specify OSS$_CLASS_NAME, $GET_SECURITY returns the full object class name.

OSS$_FIRST_TEMPLATE

When you specify OSS$_FIRST_TEMPLATE, $GET_SECURITY returns the name of the first template profile for the object named in the objnam argument. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS$_NEXT_OBJECT

When you specify OSS$_NEXT_OBJECT, $GET_SECURITY returns the name of the next object. A return length of 0 indicates the end of the list. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS$_NEXT_TEMPLATE

When you specify OSS$_NEXT_TEMPLATE, $GET_SECURITY returns the name of the next template. This item code allows you to step through a list of an object's templates. A return length of 0 indicates the end of the list. This item code is valid only for security class objects. If the clsnam is not Security_Class, SS$_INVCLSITM is returned.

OSS_OBJECT_NAME

When you specify OSS$_OBJECT_NAME, $GET_SECURITY returns the name of the object.

OSS$_OWNER

When you specify OSS$_OWNER, $GET_SECURITY returns the owner of the object.

OSS$_PROTECTION

When you specify OSS$_PROTECTION, $GET_SECURITY returns the protection code of the object.

Description

The Get Security service returns information about security characteristics of a selected object. Security characteristics include such information as the protection code, the owner, and the access control list (ACL). The security management services, $GET_SECURITY and $SET_SECURITY, maintain a single master copy of a profile for every security object in an OpenVMS Cluster environment. They also ensure that only one process at a time can modify an object's security profile.

When you call $GET_SECURITY, the service selects the specified protected object and fetches a local copy of the object's security profile.

The context for a security management operation can be established through either $GET_SECURITY or $SET_SECURITY. Whenever the context is set by one service, the other service can use it, provided the necessary locks are being held. If you intend to modify the profile, you must set the write lock flag (OSS$M_WLOCK) when you establish the context.

There are many situations in which the contxt argument is essential. By establishing a context for an ACL operation, for example, a caller can retain an ACL position across calls to $GET_SECURITY so that a set of ACEs can be read and modified sequentially. A security context is released by a call to $SET_SECURITY or $GET_SECURITY that sets the OSS$M_RELCTX flag. Once the context is released, the user-supplied context longword is set to 0.

Required Access or Privileges

Read or control access to the object is required.

Required Quota

None

Related Services

$SET_SECURITY

Condition Values Returned

Format

SYS$GET_SYS_ALIGN_FAULT_DATA buffer ,buffer_size ,return_size

C Prototype

int sys$get_sys_align_fault_data
   (void *buffer, int buffer_size, int *return_size);

Arguments

The user buffer in which the alignment fault data is to be stored. The buffer argument is the 32- or 64-bit virtual address of this buffer.

The size, in bytes, of the buffer specified by the buffer argument.

The amount of data, in bytes, stored in the buffer. The return_size argument is the 32- or 64-bit virtual address of a naturally aligned longword into which the service returns the amount of data, in bytes, stored in the buffer. The return_size argument is set to 0 if there is no data in the buffer.

Description

The Get System Alignment Fault Data service obtains data from the system alignment fault buffer if buffered system alignment fault data reporting has been enabled.

When buffered system alignment fault data reporting is enabled, the operating system writes each alignment fault into a system-allocated buffer. The user must poll this buffer periodically to read the data.

The user must call the $INIT_SYS_ALIGN_FAULT_REPORT service to enable buffered system alignment fault data reporting. For more information, see the $INIT_SYS_ALIGN_FAULT_REPORT service.

Required Access or Privileges

CMKRNL privilege is required.

Required Quota

None

Related Services

$GET_ALIGN_FAULT_DATA, $INIT_SYS_ALIGN_FAULT_REPORT, $PERM_DIS_ALIGN_FAULT_REPORT, $PERM_REPORT_ALIGN_FAULT, $START_ALIGN_FAULT_REPORT, $STOP_ALIGN_FAULT_REPORT, $STOP_SYS_ALIGN_FAULT_REPORT

Condition Values Returned

Format

SYS$GET_UNWIND_ENTRY_INFO pc, get_ue_block, name

C Prototype

int SYS$GET_UNWIND_ENTRY_INFO
   (unsigned __int64 pc, void *get_ue_block, void *name);

Arguments

Input quadword, target PC (that is, the PC for a code region the user wants unwind information for).

Address of a 4-quadword block to be filled in. That is, input the address of a 4 quadword block and, on successful returned status, that block will be updated with the following information:

Optional, that is, may be zero. If the name parameter is specified and if a name was registered for the unwind region, then the descriptor pointer and length are updated to point to that stored name. Note that if the name parameter is specified but no name exists in the unwind tables, then the name descriptor is updated to zero length.

Description

Get fixed up unwind entry information relevant to the input instruction pointer (IP).

Required Access or Privileges

None

Required Quota

None

Related Services

SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE. Also see LIB$GET_UIB_INFO in VSI OpenVMS Calling Standard.

Condition Values Returned

Format

SYS$GET_USER_CAPABILITY
   cap_num [,select_num] [,select_mask] [,prev_mask] [,flags]

C Prototype

int sys$get_user_capability
   (*cap_num, int *select_num, struct _generic_64 *select_mask,   
    struct _generic_64 *prev_mask, struct _generic_64 *flags);

Arguments

Capability number to be reserved by the calling kernel thread. This number can range from 1 to 16 for an explicit request, or the symbolic constant CAP$K_GET_FREE_CAP can be specified to get the next available user capability. The cap_num argument is the 32- or 64-bit address of the longword containing the user capability number or symbolic constant.

The number of the user capability selected by the service call. The select_num argument is the 32- or 64-bit address of a longword into which the system writes the user capability number. For an explicit numeric request, the value returned in this longword will match that specified in cap_num; otherwise, this cell contains the next available user capability.

A quadword bit mask with a single bit position set, reflecting the user capability selected by the service. The select_mask argument is the 32- or 64-bit address of a quadword into which the system writes the selected user capability bit mask. This bit mask is the most efficient method for indicating the reserved user capability with the $CPU_CAPABILITIES and $PROCESS_CAPABILITIES services.

The previous user capability reservation mask before execution of this service call. The prev_mask argument is the 32- or 64-bit address of a quadword into which the service writes a quadword bit mask specifying the previously reserved user capabilities taken from the global cell SCH$GQ_RESERVED_USER_CAPS.

Options selected for the user capability reservation. The flags argument is a quadword bit vector wherein a bit corresponds to an option.

Each option (bit) has a symbolic name, which the $CAPDEF macro defines. The flags argument is constructed by performing a logical OR operation using the symbolic names of each desired option.

At this time, all bits are reserved to OpenVMS and must be 0.

Description

The Reserve a User Capability service provides a way for discrete processes to communicate and synchronize their use of a user capability in the system. This service uses the global cell SCH$GQ_RESERVED_USER_CAPS to indicate that a particular user capability has been reserved. $GET_USER_CAPABILITY can also return the current reservation state of all user capabilities in the system.

Reservation of a user capability can be made for an explicit number or for the next available number. The selected user capability is returned to the caller through a numeric value in select_num or by a quadword bit mask in select_mask.

This service does not directly enforce unique use of the individual user capabilities; it simply provides a common informational and control resource for processes using the other capability scheduling services. Code threads that do not use this service to verify whether a user capability is available are still at risk if differing usages conflict.

Required Privileges

The caller must have both ALTPRI and WORLD privileges to call $GET_USER_CAPABILITY to reserve a user capability. No privileges are required if $GET_USER_CAPABILITY is called only to retrieve the current user capability reservation mask.

Required Quota

None

Related Services

$FREE_USER_CAPABILITY, $CPU_CAPABILITIES, $PROCESS_CAPABILITIES

Condition Values Returned

Format

SYS$GOTO_UNWIND target_invo ,target_pc ,[new_r0] ,[new_r1]

C Prototype

int sys$goto_unwind
   (void *target_invo, void *(*(target_pc)), unsigned __int64 *new_r0,
    unsigned __int64 *new_r1); 

Arguments

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, an exit unwind is initiated.

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, a system-defined target PC is assumed and execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

The address of a location that contains the value to place in the saved R0 location of the mechanism argument vector. The contents of this location are then loaded into the processor R0 register at the time that execution continues in the target invocation.

If the new_r0 argument is omitted, the contents of the processor R0 register at the time of the call to $GOTO_UNWIND are used.

Address of a location that contains the value to place in the saved R1 location of the mechanism argument vector. The contents of the location are then loaded into the processor R1 register at the time that execution continues in the target invocation.

If the new_r1 argument is omitted, the contents of the processor R1 register at the time of the call to $GOTO_UNWIND are used.

Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND

Condition Values Returned

Format

SYS$GOTO_UNWIND target_invo ,target_pc ,[NewRetVal] , [NewRetVal2]

C Prototype

int sys$goto_unwind_64
   (void *target_invo_64, void *(*(target_pc_64)),
    unsigned_int64 *new_retval, unsigned_int64 *newretval2);

Arguments

The address of a location that contains a handle for the target invocation.

If you do not specify the target_invo argument, or if the handle value is 0, the effect of the call is undefined.

The address of a location that contains the address at which execution should continue in the target invocation.

If the target_pc argument is omitted or the value is 0, execution resumes at the location specified at the return address for the call frame of the target procedure invocation.

If the target_invo argument is omitted or the value is 0, the target_pc argument is ignored. In this case, a system-defined target PC is assumed.

The address of a location that contains the value to place in the saved RetVal location of the mechanism argument vector. The contents of this location are then loaded into RetVal at the time that execution continues in the target invocation.

If the NewRetVal argument is omitted, the contents of RetVal at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R0 in SYS$GOTO_UNWIND for compatibility with Alpha.

The address of a location that contains the value to place in the saved RetVal2 location of the mechanism argument vector. The contents of the location are then loaded into RetVal2 at the time that execution continues in the target invocation.

If the NewRet2 argument is omitted, the contents of RetVal2 at the time of the call to $GOTO_UNWIND_64 are used.

This argument is called New_R1 in SYS$GOTO_UNWIND for compatibility with Alpha.

Description

The Unwind Call Stack service provides the function for a procedure to unwind the call stack.

Required Access or Privileges

None

Required Quota

None

Related Services

$UNWIND

Condition Values Returned

Format

SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]

C Prototype

int sys$grantid
   (unsigned int *pidadr, void *prcnam, struct _generic_64 *id, void *name,
    unsigned int *prvatr, unsigned int segment);

Arguments

Process identification (PID) number of the process affected when $GRANTID completes execution. The pidadr argument is the address of a longword containing the PID of the process to be affected. You use –1 to indicate the system rights list. When pidadr is passed, it is also returned; therefore, you must pass it as a variable rather than a constant. If you specify neither pidadr nor prcnam, your own process is used.

Process name on which $GRANTID operates. The prcnam argument is the address of a character string descriptor containing the process name. The maximum length of the name is 15 characters. Because the UIC group number is interpreted as part of the process name, you must use pidadr to specify the rights list of a process in a different group. If you specify neither pidadr nor prcnam, your own process is used.

Identifier and attributes to be granted when $GRANTID completes execution. The id argument is the address of a quadword containing the binary identifier code to be granted in the first longword and the attributes in the second longword.

Use the id argument to modify the attributes of the identifier.

You must specify either id or name. Because the id argument is returned as well as passed if you specify name, you must pass it as a variable rather than a constant in this case.

Name of the identifier granted when $GRANTID completes execution. The name argument is the address of a descriptor pointing to the name of the identifier. The identifier is granted as it is created. You must specify either id or name.

Previous attributes of the identifier. The prvatr argument is the address of a longword used to store the attributes of the identifier if it was previously present in the rights list. If you added rather than modified the identifier, prvatr is ignored.

Description

The Grant Identifier to Process service adds the specified identifier to the rights list of the process or the system. If the identifier is already in the rights list, its attributes are modified to those specified. This service is meant to be used by a privileged subsystem to alter the access rights profile of a user, based on installation policy. It is not meant to be used by the general system user.

Note that a value of 0 in either of the preceding tables indicates that the contents of the address specified by the argument is the value 0. The word omitted indicates that the argument was not supplied.

Required Access or Privileges

You need CMKRNL privilege to invoke this service. In addition, you need GROUP privilege to modify the rights list of a process in the same group as the calling process (unless the process has the same UIC as the calling process). You need WORLD privilege to modify the rights list of a process outside the caller's group. You need SYSNAM privilege to modify the system rights list.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $HASH_PASSWORD, $IDTOASC, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

Because the rights database is an indexed file accessed with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the VSI OpenVMS Record Management Services Reference Manual.

Format

SYS$HASH_PASSWORD pwd ,alg ,[salt] ,usrnam ,hash

C Prototype

int sys$hash_password
   (void *pwd, unsigned char alg, unsigned short int salt, void *usrnam,
    struct _generic_64 *hash);

Arguments

ASCII password string to be encrypted. The pwd argument is the address of a character string descriptor pointing to the ASCII password. The password string can contain between 1 and 32 characters and use the uppercase characters A through Z, the numbers 0 through 9, the dollar sign ($), and the underscore (_).

The caller must validate the password string before calling $HASH_PASSWORD to ensure that only permitted characters are included.

Algorithm used to hash the ASCII password string. The alg argument is an unsigned byte specifying the hash algorithm.

Values ranging from 128 to 255 are reserved for customer use; the constant UAI$K_CUST_ALGORITHM defines the start of this range.

You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with the $GETUAI system service to retrieve the primary and secondary password hash algorithms for a user.

Value used to increase the effectiveness of the hash. The salt argument is an unsigned word containing 16 bits of data that is used by the hash algorithms when encrypting a password for the associated user name. The $GETUAI item code UAI$_SALT is used to retrieve the SALT value for a given user. If you do not specify a SALT value, $HASH_PASSWORD uses the value of 0.

Name of the user associated with the password. The usrnam argument is the address of a descriptor pointing to a character text string containing the user name. The current password encryption algorithm (UAI$C_PURDY_S) folds the user name into the ASCII password string to ensure that different users with the same password produce different hash values. This argument must be supplied for all calls to $HASH_PASSWORD but is ignored when using the CRC algorithm (UAI$C_AD_II).

Output hash value representing the encrypted password. The hash argument is the address of an unsigned quadword to which $HASH_PASSWORD writes the output of the hash. If you use the UAI$C_AD_II algorithm, the second longword of the hash is always set to 0.

Description

The Hash Password service applies the hash algorithm you select to an ASCII password string and returns a quadword hash value that represents the encrypted password.

Other OpenVMS password services allow spaces, tabs, and other blank characters from the user, but they remove those spaces before passing the string to $HASH_PASSWORD. Before calling $HASH_PASSWORD, all white space must be removed from the password string to ensure proper comparison with passwords created by other services.

Required Access or Privileges

None

Required Quota

None

Related Services

$GETUAI, $SETUAI.

Use $GETUAI to get the values for the salt and alg arguments. Use $SETUAI to store the resulting hash using the item codes UAI$_PWD and UAI$_PWD2.

For more information, see the appendix on implementing site-specific security policies in the VSI OpenVMS Programming Concepts Manual.

Condition Values Returned

Format

SYS$HIBER

C Prototype

int sys$hiber (void);

Arguments

None.

Description

The Hibernate service allows a process to make itself inactive but to remain known to the system so that it can be interrupted; for example, to receive ASTs. A hibernate request is a wait-for-wake-event request. When you call the Wake Process from Hibernation ($WAKE) service or when the time specified with the Schedule Wakeup ($SCHDWK) service occurs, the process continues execution at the instruction following the Hibernate call.

In VAX MACRO, you can call the Hibernate service only by using the $name_S macro.

A hibernating process can be swapped out of the balance set if it is not locked into the balance set.

An AST can interrupt the wait state caused by $HIBER if the access mode at which the AST is to execute is equal to or more privileged than the access mode from which the hibernate request was issued and the process is enabled for ASTs at that access mode.

When the AST service routine completes execution, the system reexecutes the $HIBER service on behalf of the process. If a wakeup request has been issued for the process during the execution of the AST service routine (either by itself or another process), the process resumes execution. If a wakeup request has not been issued, it continues to hibernate.

If one or more wakeup requests are issued for the process while it is not hibernating, the next hibernate call returns immediately; that is, the process does not hibernate. No count of outstanding wakeup requests is maintained.

ISTAT=SYS$HIBER()

Required Access or Privileges

None

Required Quota

None

Related Services

$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND, $WAKE

Condition Values Returned

Format

SYS$ICC_ACCEPT
   conn_handle ,[accept_buf] ,[accept_len] ,[user_context] ,[flags]

C Prototype

int sys$icc_accept
   (unsigned int conn_handle, char * accept_buf, unsigned int accept_len,
    unsigned int user_context, unsigned int flags);

Arguments

The handle of the requested connection.

A buffer of up to 1000 bytes of accept data that is sent to the source of the connection at the completion of the connection process.

The actual number of bytes in accept_buf to be sent.

A user-specified value that is subsequently returned on any disconnect or data events on this connection.

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, and that the AST will not be called.

Description

This service is used by a server to respond to an incoming connection request. The $ICC_ACCEPT service may only be called after receiving a connection request AST.

At the completion of the service, the connection is open and data can be exchanged. Once opened, there is no logical distinction between a connection opened by a client with the Connect service or a server with the Accept service.

A server can reject a Connection request by calling the $ICC_REJECT service.

Required Access or Privileges

None

Required Quota

$ICC_ACCEPT changes the process BYTLM quota for the length of the accept_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.

Related Services

$ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_CLOSE_ASSOC assoc_handle

C Prototype

int sys$icc_close_assoc (unsigned int assoc_handle);

Arguments

The handle of the association to be closed.

Description

This service closes the application's association with ICC. If multiple associations are open, only the specified association is closed. When an association is closed, any active connections on that association are disconnected. If not explicitly closed by the application, associations opened in user mode will be closed at image exit; associations opened in inner modes will be closed at process termination.

All operations on an association must occur in the access mode at which the association was opened.

When an association is closed, the entry (if any) in the simple clusterwide association registry is removed.

Required Access or Privileges

None

Required Quota

None

Related Services

$ICC_ACCEPT, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_CONNECT
   ios_icc ,[astadr] ,[astprm] ,assoc_handle ,conn_handle ,remote_assoc
   ,[remote_node] ,[user_context] ,[conn_buf] ,[conn_buf_len] ,[return_buf]
   ,[return_buf_len] ,[retlen_addr] ,[flags]

C Prototype

int sys$icc_connect
   (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params),
    __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle,
    void *remote_assoc, void *remote_node, unsigned int user_context,
    char *conn_buf, unsigned int conn_buf_len, char *return_buf,
    unsigned int return_buf_len, unsigned int *retlen_addr,
    unsigned int flags);

Arguments

I/O status block:

Completion status values:

SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM, SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM, SS$_NOSUCHOBJ, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT, SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE

The second longword is undefined unless the completion code is SS$_REJECT. In this case, the application-defined rejection reason code is supplied by the server when $ICC_REJECT is called.

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

The handle of the association on which the connection is to be opened. The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates that the default association is to be used (and opened if necessary).

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of a longword into which $ICC_CONNECT writes the connection handle of the created connection on a successful call.

An ASCII character string (31 characters maximum) specifying the name of the target application to connect to. Association names are case sensitive.

The name of the node where the target association resides. A null or blank string can be used to indicate the local node. If omitted (by passing zero by value), the simple clusterwide association registry is to be used. Each node name is a one-to-six character SCS node name. A comma-delimited list of nodes may be specified, indicating that one is to be chosen at random.

A user-specified value to be subsequently returned on any disconnect or data events on this connection.

A buffer of up to 1000 bytes of connection data to be sent to the target of the connection during the connection process.

The number of bytes in conn_buf to be sent.

A buffer of up to 1000 bytes in length to receive any incoming connection accept or reject data returned.

The length of the supplied return_buf.

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of a longword into which $ICC_CONNECT writes the actual length (in bytes) of any user accept or reject data returned in the buffer return_buf.

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, indicating that the AST will not be called.

Description

This service establishes a connection to a remote application over an open association. Connections must be opened in the same mode as their association. If the user provides the default association constant ICC$C_DFLT_ASSOC_HANDLE as its association handle, the default association will be used; it will be opened if it is not already open. Multiple connections are possible over a single association. When completion is signaled by the AST routine, the application must check the completion status field of the IOS_ICC to determine if the server has accepted or rejected the connection request. The number of connections is subject to process BYTLM quota.

At image exit, as a result of closing any open user mode associations, all user mode connections are disconnected. Inner mode connections are the responsibility of the inner mode code, but are disconnected at process termination when inner mode associations are closed. Connections are only visible to the mode in which they were opened.

A client opens connections with the $ICC_CONNECT service; a server opens connections with the $ICC_ACCEPT service.

Required Access or Privileges

SYSNAM, or access via ICC Security Object. For more information, see the VSI OpenVMS System Manager's Manual.

Required Quota

$ICC_CONNECT changes the process BYTLM quota for the length of the conn_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.

If $ICC_OPEN_ASSOC is not called before $ICC_CONNECT, the default value of MAXFLOWBUFCNT is used (currently 5).

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_CONNECTW
   ios_icc ,[astadr] ,[astprm] ,assoc_handle ,conn_handle ,remote_assoc
   ,[remote_node] ,[user_context] ,[conn_buf] ,[conn_buf_len] ,[return_buf]
   ,[return_buf_len] ,[retlen_addr] ,[flags]

C Prototype

int sys$icc_connectw
   (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params),
    __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle,
    void *remote_assoc, void *remote_node, unsigned int user_context,
    char *conn_buf, unsigned int conn_buf_len, char *return_buf,
    unsigned int return_buf_len, unsigned int *retlen_addr,
    unsigned int flags);

Format

SYS$ICC_DISCONNECT
   conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnect
   (unsigned int conn_handle, struct _iosb, *iosb,
    void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf,
    unsigned int disc_buf_len);

Arguments

The ID of the connection to be disconnected.

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

A buffer of up to 1000 bytes of disconnect data to be sent to the partner in the connection when notifying it that disconnection is being initiated. Delivery of this data is not guaranteed.

The number of bytes in disc_buf to be sent.

Description

This service must be called in the mode in which the association was opened.

This service terminates the specified connection. After this service is called, no further communication is possible over this connection. All outstanding data transmission and reception functions are terminated with an error before completion is signaled by calling the AST (if supplied).

A connection may be disconnected by either party. Proper programming procedure for network communications strongly recommends that the party that last received a message initiate the disconnection. If the party that last sent a message initiates the disconnection, there is no guarantee that the message was delivered.

Similarly, although this interface provides the ability to send disconnect data, only noncritical information should be transmitted with the disconnect data mechanism, because there is no guarantee that the data will have been received or acted upon by the other party to the connection.

Required Access or Privileges

None

Required Quota

BYTLM (disc_buf)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_DISCONNECTW
   conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnectw
   (unsigned int conn_handle, struct _iosb, *iosb,
    void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf,
    unsigned int disc_buf_len);

Format

SYS$ICC_OPEN_ASSOC
   assoc_handle ,[assoc_name] ,[logical_name] ,[logical_table]
   ,[conn_event_rtn] ,[disc_event_rtn] ,[recv_rtn] ,[maxflowbufcnt]
   ,[prot]

C Prototype

int sys$icc_open_assoc
   (unsigned int *assoc_handle, void *assoc_name, void *logical_name,
    void *logical_table, void (*conn_event_rtn)(__unknown_params),
    void (*disc_event_rtn)(__unknown_params),
    void (*recv_rtn)(__unknown_params), unsigned int maxflowbufcnt,
    unsigned int prot);

Arguments

The 32-bit or 64-bit address (on Alpha and Integrity server systems) into which $ICC_OPEN_ASSOC writes the handle assigned to the opened association.

An ASCII character string of up to 31 characters in length specifying the name of the application opening the association. Null (0 length), and empty or blank association names are not allowed. If this argument is omitted (that is, a zero is passed in by value), it signifies that the user wants to open the default association. This argument is case sensitive.

A logical name in a clusterwide logical name table used to maintain the simple association registry. The logical name represents the name of the service provided by the application. Logical names are case sensitive.

The table containing the logical name logical_name. Logical name tables are converted to uppercase. Unless your application requires an application-specific logical name table, this argument should be either the default ICC Registry search list (ICC$REGISTRY), or the default registry table (ICC$REGISTRY_TABLE).

The address of the AST routine to be called for incoming connect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

You must have a conn_event_rtn to operate as a server.

The address of the AST routine to be called for incoming disconnect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode). The arguments, conn_event_rtn, and disc_event_rtn, may reference the same routine.

The address of the AST routine to be called for incoming new data events.

If the user provides this routine, it indicates that the user will supply a buffer of the size required (specified in an argument to the recv_rtn at each call) each time one is requested. If the user supplies this routine, receive calls should only be issued after receive events arrive and sufficient buffer space has been allocated to handle the incoming data.

This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

The maximum number of pending inbound messages (per connection) that ICC will allow the user before initiating flow control. A message is pending if it is being held within ICC but no receive call(s) are outstanding from the user.

Default = 5 (Pass 0 to get the default)

This argument is ignored for non-server applications.

The default protection scheme for this association is as follows:

0 - access for everyone (default)

1 - stops WORLD access

2 - stops both WORLD and GROUP access

Advanced access control is provided by ICC Security objects. For information about ICC system management and security, see the VSI OpenVMS System Manager's Manual.

Description

This service declares an application association with ICC. Servers must make this call to declare or register their name and to indicate their readiness to receive incoming connections. Although a client is permitted to call this routine, it is unnecessary for simple applications. A client application that wishes to be notified of disconnection events or Receive Data events must call the $ICC_OPEN_ASSOC service.

A client can open a connection without specifying an open association; this automatically creates a default association name of ICC$PID_nnnnnnnn (where nnnnnnnn is a character representation of the Process ID).

NETMBX privilege is required to open any association.

The association name space is a controlled resource. For information about managing this resource, see the VSI OpenVMS System Manager's Manual.

An attempt to open an association with a name not authorized as described in the VSI OpenVMS System Manager's Manual will fail with the error SS$_NOPRIV returned to the caller. In addition to making entries in the system's local association name space, a call to $ICC_OPEN_ASSOC may also make an entry in a simple clusterwide registry of active associations.

An association may only be accessed from the mode in which it was opened. Inner modes are prevented from using the default association.

An application can open any number of associations subject to available process BYTLM quota. Currently, there is a systemwide limit of 512 open associations. There is no limit imposed clusterwide.

Description of User-Supplied Routines (ASTs)

When opening an association, the user may optionally supply a connect/disconnect AST and/or a Data Event AST. These routines will be used for all connections established over the specified association. In addition, for any of the asynchronous services (those provided with both an immediate return and a "W" form), a completion AST may be supplied by the user. This section describes these ASTs.

ConnDiscRtn  event_type ,conn_handle ,data_len ,data_bfr ,P5 ,P6 ,P7

void ConDiscRtn
   (unsigned int event_type, unsigned int conn_handle, 
    unsigned int data_len, char *data_bfr,
    unsigned int P5, unsigned int P6, char *P7);

event_type
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

ICC$C_EV_CONNECT      - Connection event 
ICC$C_EV_DISCONNECT   - Disconnection event 

conn_handle
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

data_len
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

data_bfr
Type:       character-coded text string 
Access:     read only 
Mechanism:  by 32-bit or 64-bit value (Alpha and Integrity servers) 

P5
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

P6
Type:       quadword (Alpha and Integrity servers 
Access:     read only 
Mechanism:  by value 

P7
Type:       character-coded text string 
Access:     read only 
Mechanism:  by reference 

DataEventRtn  message_size ,conn_handle ,user_context

void DataEventRtn
   (unsigned int message_size, unsigned int conn_handle, 
    unsigned int user_context);

message_size
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

conn_handle
Type:       longword (unsigned) 
Access:     read only 
Mechanism:  by value 

user_context
Type:       quadword (Alpha and Integrity servers 
Access:     read only 
Mechanism:  by value 

Condition Values Returned

Format

SYS$ICC_RECEIVE
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

sys$icc_receive
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm,
    char *recv_buf, unsigned int recv_buf_len);

Arguments

The handle of the fully established connection.

I/O status block:

Completion codes:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKDISCON, SS$_BUFOVL, SS$_ACCVIO

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of the buffer to receive the incoming data. The length of this buffer is specified by the argument recv_buf_len.

The length (in bytes) of the buffer available to hold the incoming data. This value specifies the length of the buffer recv_buf.

IOS_ICC Arguments:

This parameter is returned in the ios_icc. $ICC_RECEIVE writes the actual length of the incoming data message received from the target application (in bytes) into offset ios_icc$l_rcv_len of the ios_icc.

This parameter is returned in the ios_icc. $ICC_RECEIVE writes the Request/Response handle into offset ios_icc$l_req_handle of the ios_icc. The request_handle argument is nonzero if the application is expected to reply to this message.

This parameter is returned in the ios_icc. The $ICC_RECEIVE service writes the maximum length (in bytes) of the expected Reply message into offset ios_icc$l_reply_len of the ios_icc, if request_handle is nonzero.

Description

This service receives a single message over a connection. If a Request ID is returned at completion, the partner has used a Transceive system service and requires data to be returned with a Reply service.

For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional values are returned by the ios_icc data structure.

Required Access or Privileges

None

Required Quota

BYTLM

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_RECEIVEW
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,recv_buf ,recv_buf_len

C Prototype

sys$icc_receivew
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm,
    char *recv_buf, unsigned int recv_buf_len);

Format

SYS$ICC_REJECT
   conn_handle, [reject_buf], [reject_buf_len], [reason]

C Prototype

int sys$icc_reject
   (unsigned int conn_handle, char * reject_buf,
    unsigned int reject_buf_len, unsigned int reason);

Arguments

The handle of the requested connection.

A buffer of up to 1000 bytes of reject data to be sent to the source of the connection at the completion of the rejection process.

The number of bytes in reject_buf to be sent.

User-specified reject reason code to be supplied to the remote application.

Default = SS$_REJECT

Description

This service is used by a server to refuse an incoming connection request. The $ICC_REJECT service may only be called after receiving a connection request AST. After the completion of the service, the client is notified that the connection was not opened.

Required Access or Privileges

None

Required Quota

None

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_REPLY
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,reply_buf ,reply_len

C Prototype

sys$icc_reply
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm, char *reply_buf,
    unsigned int reply_len);

Arguments

The handle of the fully established connection.

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of the buffer containing the reply data to be sent. The length of this buffer is specified by the argument reply_len.

The length (in bytes) of the reply data to be sent over the connection. This value specifies the length of the buffer reply_buf. ICC segments larger buffers internally.

The maximum Reply length is the smaller of the Reply buffer size supplied in the $ICC_RECEIVE call, or 1MB.

IOS_ICC Argument:

This parameter is passed through the ios_icc. The Request/Response handle from the received Transceive request is placed at offset ios_icc$l_replyto_handle of the ios_icc.

Description

This service is almost identical to the $ICC_TRANSMIT system service in that it sends a single message over a connection. The only difference is that it is used in response to the reception of a Request Handle in a previous Receive Data system service.

When completion is signaled by calling the AST (if supplied), the data has been delivered to the communications system, but not necessarily to the application at the other end of the connection. The user can reuse the buffer after completion has been signaled.

Alternatively, if the synchronous completion option was requested at connection time, the service may return the optional success status, SS$_SYNCH. When SS$_SYNCH is returned, completion has occurred, and no AST will be delivered.

Required Access or Privileges

None

Required Quota

BYTLM (for Reply buffer)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_REPLYW
   conn_handle, ios_icc, [astadr], [astprm], reply_buf, reply_len

C Prototype

sys$icc_replyw
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm,
    char *reply_buf, unsigned int reply_len);

Format

SYS$ICC_TRANSCEIVE
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transceive
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm, char *send_buf,
    unsigned int send_len);

Arguments

The handle of the fully established (open) connection.

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_BUFOVFL, SS$_LINKABORT, SS$_LINKDISCON

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of the buffer containing the data to be sent. The length of this buffer is specified by the argument send_len.

The length (in bytes) of the data to be sent over the connection. This value specifies the length of the buffer send_buf.

IOS_ICC Arguments:

This parameter is passed through the ios_icc. The $ICC_TRANSCEIVE service writes the actual length (in bytes) of the reply data received into offset ios_icc$l_txrcv_len of the ios_icc. This value represents how much data in reply_buf was returned by the target application.

This parameter is passed through the ios_icc. The 32-bit or 64-bit address (on Alpha and Integrity server systems) of the buffer available to receive the incoming reply message is placed in offset ios_icc$a_reply_buffer of the ios_icc.

This parameter is passed through the ios_icc. The length (in bytes) of the buffer to receive the reply message. This value specifies the length of the buffer reply_buf. This value is placed in offset ios_icc$l_txreply_len of the ios_icc.

Description

This service sends a single message over a connection and then waits for a reply. When completion is signaled by calling the AST (if supplied), the data has been delivered to the application at the other end of the connection and that application has delivered a reply, now present in the reply buffer. The user can reuse the send and reply buffers after completion.

For efficiency reasons, the number of parameters on this routine has been limited to six parameters. Three additional parameters are passed by the ios_icc data structure.

Required Access or Privileges

None

Required Quota

BYTLM (Send and Reply buffers)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_TRANSCEIVEW
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transceivew
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm, char *send_buf,
    unsigned int send_len);

Format

SYS$ICC_TRANSMIT
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transmit
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm,
    char *send_buf, unsigned int send_len);

Arguments

The handle of the fully established (open) connection to send the data over.

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_INSFMEM, SS$_LINKABORT, SS$_LINKDISCON

The AST routine to be executed when the operation completes.

The parameter to be passed to the AST routine.

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of the buffer containing the data to be sent. The length of this buffer is specified by the argument send_len.

The length (in bytes) of the data to be sent over the connection. This value specifies the length of the buffer send_buf. The maximum transmission size is 1MB.

Description

This service sends a single message over a connection. When completion is signalled by calling the AST (if supplied), the data has been delivered to the communications system, but not necessarily to the system or application at the other end of the connection. After completion, the user can reuse the buffer.

Alternatively, if the synchronous completion option was requested at connection time, the service may return the optional success status, SS$_SYNCH. When SS$_SYNCH is returned, completion has occurred, and no AST will be delivered.

Required Access or Privileges

None

Required Quota

BYTLM (send_buf)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMITW

Condition Values Returned

Format

SYS$ICC_TRANSMITW
   conn_handle ,ios_icc ,[astadr] ,[astprm] ,send_buf ,send_len

C Prototype

sys$icc_transmitw
   (unsigned int conn_handle, struct _ios_icc *ios_icc,
    void (*astadr)(__unknown_params), __int64 astprm, char *send_buf,
    unsigned int send_len);

Format

SYS$IDTOASC id ,[namlen] ,[nambuf] ,[resid] ,[attrib] ,[contxt]

C Prototype

int sys$idtoasc
   (unsigned int id, unsigned short int *namlen, void *nambuf,
    unsigned int *resid, unsigned int *attrib, unsigned int *contxt);

Arguments

Binary identifier value translated by $IDTOASC. The id argument is a longword containing the binary value of the identifier. To determine the identifier names of all identifiers in the rights database, you specify id as –1 and call $IDTOASC repeatedly until it returns the status code SS$_NOSUCHID. The identifiers are returned in alphabetical order.

Number of characters in the identifier name translated by $IDTOASC. The namlen argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a word containing the length of the identifier name written to nambuf.

Identifier name text string returned when $IDTOASC completes the translation. The nambuf argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a descriptor pointing to the buffer in which the identifier name is written.

Identifier value of the identifier name returned in nambuf. The resid argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a longword containing the 32-bit code of the identifier.

Mask of attributes associated with the identifier returned in resid. The attrib argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a longword containing the attribute mask.

Context value used when repeatedly calling $IDTOASC. The contxt argument is the 32- or 64-bit address (on Alpha and Integrity server systems) of a longword used while $IDTOASC searches for all identifiers. The context value must be initialized to the value 0, and the resulting context of each call to $IDTOASC must be presented to each subsequent call. After contxt is passed to $IDTOASC, you must not modify its value.

Description

The Translate Identifier to Identifier Name service translates the specified binary identifier value to an identifier name. While the primary purpose of this service is to translate the specified identifier to its name, you can also use it to find all identifiers in the rights database. Owner or read access to the rights database is required. To determine all the identifiers, call $IDTOASC repeatedly until it returns the status code SS$_NOSUCHID. When SS$_NOSUCHID is returned, $IDTOASC has returned all the identifiers, cleared the context value, and deallocated the record stream.

If you complete your calls to $IDTOASC before SS$_NOSUCHID is returned, use $FINISH_RDB to clear the context value and deallocate the record stream.

When you use wildcards with this service, the records are returned in identifier name order.

Required Access or Privileges

None, unless the id argument is NAME_HIDDEN, in which case you must hold the identifier or have read access to the rights list.

Required Quota

None

Related Services

$ADD_HOLDER, $ADD_IDENT, $ASCTOID, $CHECK_ACCESS, $CHKPRO, $CREATE_RDB, $ERAPAT, $FIND_HELD, $FIND_HOLDER, $FINISH_RDB, $FORMAT_ACL, $FORMAT_AUDIT, $GET_SECURITY, $GRANTID, $HASH_PASSWORD, $MOD_HOLDER, $MOD_IDENT, $MTACCESS, $PARSE_ACL, $REM_HOLDER, $REM_IDENT, $REVOKID, $SET_SECURITY

Condition Values Returned

Because the rights database is an indexed file that you access with OpenVMS RMS, this service can also return RMS status codes associated with operations on indexed files. For descriptions of these status codes, refer to the VSI OpenVMS Record Management Services Reference Manual.

Format

SYS$IEEE_SET_FP_CONTROL [clrmsk] ,[setmsk] ,[prvmsk]

C Prototype

int sys$ieee_set_fp_control
   (struct _ieee *clrmsk,  struct _ieee *setmsk, struct _ieee *prvmsk);

Arguments

Address of a quadword bit mask to be cleared in the IEEE floating-point control register.