rexxsyslib.library Reference

Comprehensive function reference for rexxsyslib.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/rexxsyslib).

This page documents 17 functions of rexxsyslib.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

ClearRexxMsg()

ClearRexxMsg - Releases and clears the argument array in a RexxMsg

Synopsis

ClearRexxMsg(msgptr, count) A0 D0

VOID ClearRexxMsg(struct RexxMsg*,ULONG)

Function

This function will DeleteArgstring() one or more argstrings from the RexxMsg and clear the slot. The count is used to select the number of slots to clear.

Inputs

msgptr - A pointer to a RexxMsg count - The number of slots to be cleared. The number can be from 1 to 16. (There are 16 slots)

Results

All of the slots in the given count will be cleared and the argstring will have been released.

See also

FillRexxMsg(), DeleteRexxMsg(), DeleteArgstring(), CreateArgstring()

CreateArgstring()

CreateArgstring - Create an argument string structure

Synopsis

argstr = CreateArgstring(string, length) D0,A0 A0 D0

UBYTE *CreateArgstring(UBYTE *, ULONG);

Function

Allocates a RexxArg structure and copies the supplied string into it. The returned pointer points at the string part of the structure and can be treated like an ordinary string pointer. (However, care must be taken that you do not change the string)

Inputs

string - A pointer at your input string length - The number of bytes of your input string you wish copied. (NOTE: You are limited to 65,535 byte strings)

Results

argstr - A pointer to the argument string. The results are returned in both A0 and D0. You should always check the result as an allocation failure would cause an error.

See also

DeleteArgstring(), LengthArgstring(), ClearRessMsg(), FillRexxMsg()

CreateRexxHostPort()

CreateRexxHostPort - Create a port for an ARexx host (V45)

Synopsis

port = CreateRexxHostPort(basename) A0

MsgPort*CreateRexxHostPort(const UBYTE *)

Function

Creates a unique port for an ARexx host.

Inputs

basename - Name basis for the port. The final name of the port is created by appending a period to the name, followed by a number to make the port name unique.

Results

result - a pointer to the port created, or NULL for failure

Notes

All resources required for the port, including memory and the signal bit are allocated by this function. To release the port and all associated resources, use DeleteRexxHostPort().

See also

DeleteRexxHostPort()

CreateRexxMsg()

CreateRexxMsg - Create an ARexx message structure

Synopsis

rexxmsg = CreateRexxMsg(port, extension, host) D0,A0 A0 A1 A2

struct RexxMsg*CreateRexxMsg(MsgPort*, UBYTE *, UBYTE *)

Function

This functions allocates an ARexx message packet. The RexxMsg consists of a standard EXEC message structure extended to include the ARexx specific information.

Inputs

port - A pointer to a public or private message port. This MUST be a valid port as this is where the message will be replied.

extension - A pointer to a NULL terminated string that is to be used
            as the default extension for the REXX scripts.  If this
            is NULL, the default is "REXX"

host - A pointer to a NULL terminated string that is to be used
       as the default host port.  The name must be the same as the
       name of the public message port that is to be the default host.
       If this field is NULL, the default is REXX.

Results

rexxmsg - A RexxMsg structure

Notes

The extension and host strings must remain valid for as long as the RexxMsg exists as only the pointer to those strings are stored.

See also

DeleteRexxMsg(), ClearRexxMsg(), FillRexxMsg()

DeleteArgstring()

DeleteArgstring - Releases an Argstring created by CreateArgstring()

Synopsis

DeleteArgstring(argstring) A0

VOID DeleteArgstring(UBYTE *)

Function

Releases an argstring. The argstring must have been created by ARexx

Inputs

argstring - A pointer to the string buffer of an argstring.

See also

CreateArgstring(), ClearRexxMsg(), FillRexxMsg()

DeleteRexxHostPort()

DeleteRexxHostPort - Delete a port of an ARexx host (V45)

Synopsis

DeleteRexxHostPort(port) A0

VOID DeleteRexxHostPort(MsgPort*)

Function

Deletes a port created by CreateRexxHostPort()

Inputs

port - Pointer to the port to be deleted. Passing NULL is a no-op.

Notes

The port passed in must have been created by CreateRexxHostPort()

See also

CreateRexxHostPort()

DeleteRexxMsg()

DeleteRexxMsg - Releases a RexxMsg structure created by CreateRexxMsg()

Synopsis

DeleteRexxMsg(packet) A0

VOID DeleteRexxMsg(struct RexxMsg*)

Function

The function releases an ARexx message packet that was allocated with CreateRexxMsg(). Any argument fields in the RexxMsg structure should be cleared before calling this function as it does not release them for you.

Inputs

packet - A pointer to a RexxMsg structure allocated by CreateRexxMsg()

Example

if (rmsg=CreateRexxMsg(myport,"myapp","MYAPP_PORT")) { / Do my think with rmsg / ClearRexxMsg(rmsg,16); / We may not want to clear all 16 / DeleteRexxMsg(rmsg); }

See also

CreateRexxMsg(), ClearRexxMsg()

FillRexxMsg()

FillRexxMsg - Fill the argument strings as needed

Synopsis

result = FillRexxMsg(msgptr, count, mask) D0 A0 D0 D1 [0:15]

BOOL FillRexxMsg(struct RexxMsg*,ULONG,ULONG)

Function

This function will convert and install up to 16 argument strings into a RexxMsg structure. The message packet's argument fields must be set to either a pointer to a NULL terminated string or an integer value The mask, bits 0 to 15, correspond to the type of value is stored in the argument slot. If the bit is cleared, the argument is a string pointer; if the bit is set, the argument is an integer.

Inputs

msgptr - Pointer to a RexxMsg (allocated via CreateRexxMsg) count - The number of argument slots to fill in. This number should be from 1 to 16.

mask - A bit mask corresponding to the 16 fields that is used to
       determine the type of the field.

Results

result - A boolean. If it is TRUE, the call worked. If it is false, some allocation did not work. All argstrings that were created will be released.

See also

ClearRexxMsg(), CreateArgstring(), DeleteArgstring(), CreateRexxMsg()

FreeRexxMsg()

Synopsis

FreeRexxMsg(rexxmsg); A0

void FreeRexxMsg(struct RexxMsg*);

Function

This function disposes a rexx message and its arguments formally created by LaunchRexxMsg(). It does not shut down the rm_Stdin and rm_Stdout streams of this message, nor does it check for the result codes. It disposes all the rexx arguments, though.

Inputs

rexxmsg - a struct RexxMsg that has been created by LaunchRexxMsg() before. Should not be used for other messages.

Notes

Do not call this function on a message that did not yet return on your reply port or REXX may crash.

See also

LaunchRexxScript(), ClearRexxMsg(), DeleteRexxMsg()

GetRexxBufferFromMsg()

GetRexxBufferFromMsg - retrieve the value of a Rexx variable (V47)

Synopsis

error = GetRexxBufferFromMsg(var,msg,out,size) A0 A2 A1 D0

LONG GetRexxBufferFromMsg(const UBYTE *var,constMessage*msg, UBYTE *buffer)

Function

Retrieves the value of an ARexx variable whose name is given as first argument, and places its length into the output buffer of the given size.

Inputs

var - Name of the variable to be read. A stem variable is fine. msg - Pointer to a rexx message received by this program defining the execution environment from which the variable is read. out - buffer to hold the value of the variable. size - size of the buffer in characters (including NUL)

Results

error - an error code from or 0 for success.

Bugs

This function only supports NUL-terminated values (which is, however, generally the case).

See also

GetRexxVarFromMsg(), SetRexxVarFromMsg(), GetRexxVar()

GetRexxVarFromMsg()

GetRexxVarFromMsg - retrieve the value of a Rexx variable (V45)

Synopsis

error = GetRexxVarFromMsg(var,msg,out) A0 A2 A1

LONG GetRexxVarFromMsg(const UBYTE *var,constMessage*msg, UBYTE *buffer)

Function

Retrieves the value of an ARexx variable whose name is given as first argument, and places its length into the output buffer.

Inputs

var - Name of the variable to be read. A stem variable is fine. msg - Pointer to a rexx message received by this program defining the execution environment from which the variable is read. out - buffer of 256 characters to hold the value of the variable.

Results

error - an error code from or 0 for success.

Bugs

This function always assumes that the target buffer is at least 256 characters long. Reading longer variables will create an error. Furthermore, this function only supports NUL-terminated values (which is generally the case, though).

See also

GetRexxBufferFromMsg(), SetRexxVarFromMsg(), GetRexxVar()

IsRexxMsg()

IsRexxMsg - Function to determine if a message came from ARexx

Synopsis

result = IsRexxMsg(msgptr) D0 A0

BOOL IsRexxMsg(struct RexxMsg*)

Function

This function can be used to determine if a message came from an ARexx program.

Inputs

msgptr - A pointer to the suspected RexxMsg.

Results

result - A boolean: TRUE if it is an ARexx message, FALSE if not.

Bugs

This function may not be fully sufficient to check whether a message really came from Rexx. For a more careful check, use the CHECKREXXMSG() macro from

See also

CreateRexxMsg()

LaunchRexxScript()

LaunchRexxScript - run a Rexx script from a Rexx host (V45)

Synopsis

msg = LaunchRexxScript(script,port,suffix,in,out) A0 A1 A2 D1 D2

struct RexxMsg*LaunchRexxScript(const UBYTE *script, constMsgPort*port, const UBYTE *suffix, BPTR in,BPTR out)

Function

Runs a rexx script from a rexx host.

Inputs

script - The script along with all of its arguments, separated by spaces. port - A private or public port the created message will be replied to when script execution terminates. suffix - file name suffix of the script. If NULL, then "REXX" is assumed. in - input file handle supplied to the script. out - output file handle supplied to the script.

Results

msg - a message that has already been send to the Rexx master for execution. If this message is retrieved on the port provided as argument, then execution is complete.

See also

CreateRexxMsg()

LengthArgstring()

LengthArgstring - Returns the length value stored in the argstring

Synopsis

length = LengthArgstring(argstring) D0 A0

ULONG LengthArgstring(UBYTE *)

Function

This function returns the length value stored in the argstring. This is NOT the same as doing a strlen() type call on the argstring. (Note that argstrings may contain NULLs)

Inputs

argstring - A pointer to an argstring that was created by ARexx

Results

length - The length of the argstring.

See also

CreateArgstring()

LockRexxBase()

LockRexxBase - Obtain a semaphore lock on the RexxBase structure

Synopsis

LockRexxBase(resource) D0

VOID LockRexxBase(ULONG)

Function

Secures the specified resource in the ARexx library base.

Inputs

resource - A manifest constant defining which resource to lock. ZERO locks all resources.

Notes

Currently, only ZERO resource type is available. You MUST make sure that you do not call this function with an undefined value as it may become defined at some future date and cause unwanted behavior.

See also

UnlockRexxBase()

SetRexxVarFromMsg()

SetRexxVarFromMsg - set the value of a Rexx variable (V45)

Synopsis

error = SetRexxVarFromMsg(var,msg,value) A0 A2 A1

LONG SetRexxVarFromMsg(const UBYTE *var,constMessage*msg, const UBYTE *value)

Function

Sets an ARexx variable whose name is given as first argument to the value given as third argument.

Inputs

var - Name of the variable to be set. A stem variable is fine. msg - Pointer to a rexx message received by this program defining the execution environment from which the variable is read. out - NUL-terminated string defining the value to be set.

Results

error - an error code from or 0 for success.

Bugs

This function only supports NUL-terminated values.

See also

GetRexxBufferFromMsg(), GetRexxVarFromMsg(), SetRexxVar()

UnlockRexxBase()

UnlockRexxBase - Release a semaphore lock on the RexxBase structure

Synopsis

UnlockRexxBase(resource) D0

VOID UnlockRexxBase(ULONG)

Function

Releases the specified resource in the ARexx library base.

Inputs

resource - A manifest constant defining which resource to unlock. This value MUST match the value used in the matching LockRexxBase() call.

Notes

Currently, only ZERO resource type is available. You MUST make sure that you do not call this function with an undefined value as it may become defined at some future date and cause unwanted behavior. You MUST make sure that you only call this function after a matching call to LockRexxBase() was made.

See also

LockRexxBase()