Synopsis

VOID ClearRexxMsg(
         struct RexxMsg * msgptr,
         ULONG count );

Function

Releases non-NULL Rexx argument strings in the first count entries
of msgptr->rm_Args and sets those entries to zero.

Inputs

msgptr - RexxMsg containing argument strings to release.
count  - Number of entries, starting at index 0; must not exceed
         MAXRMARG.

Result

None.

Notes

Every non-NULL entry in the selected range must be a valid,
allocated Rexx argument string. Do not use this function on
unconverted string pointers or integer values prepared for
FillRexxMsg(). Entries beyond count are not changed.

Bugs

The implementation does not validate count against the rm_Args
array capacity. Larger values can access memory outside the array.

See also

FillRexxMsg() DeleteArgstring() DeleteRexxMsg()

Synopsis

UBYTE * CreateArgstring(
         CONST UBYTE * string,
         ULONG length );

Function

Allocates a Rexx argument string and copies exactly length bytes from
string. The copied data is terminated with a NUL byte; its length
is stored separately.

Inputs

string - Source buffer containing at least length readable bytes.
length - Number of bytes to copy, from 0 through 65535.

Result

Pointer to the copied argument data, or NULL if allocation fails.

Notes

The caller owns the returned argument string and must release it
with DeleteArgstring(). Treat the returned data as read-only.
Embedded NUL bytes count toward the stored length. Use
LengthArgstring() rather than strlen() to obtain that length.

Bugs

The function does not reject lengths above 65535, although the
RexxArg length field is only 16 bits. LengthArgstring() cannot
report such lengths correctly.

See also

DeleteArgstring() LengthArgstring()

Synopsis

struct RexxMsg * CreateRexxMsg(
         struct MsgPort * port,
         UBYTE          * extension,
         UBYTE          * host );

Function

Allocates and initializes a RexxMsg for communication with an
ARexx interpreter or command host.

Inputs

port      - Reply port to store in the new message. If the message
            is sent, the port must remain valid until its reply.
extension - Filename extension for macro lookup, or NULL if no
            extension is supplied.
host      - Initial command host name, or NULL if none is supplied.

Result

Pointer to the new message, or NULL if allocation fails.

Notes

The message fields are initially cleared. The function stores the
extension and host pointers without copying their strings. Any
referenced storage must remain valid while the message uses it.
Passing NULL for host leaves rm_CommAddr set to NULL; this
function does not substitute the name "REXX".
Delete the message with DeleteRexxMsg() after it is no longer in
use, including by any pending recipient.

See also

DeleteRexxMsg() FillRexxMsg() IsRexxMsg()

Synopsis

LONG CVa2i(
         UBYTE * buffer );

Function

This function converts an ASCII string to a signed 32-bit integer.
The string scanning is stopped when a non-digit character is found or
the integer value would overflow.
The function returns both the number of bytes scanned
and the integer value.

Inputs

buffer (A0) - A pointer to the first character of the ASCII string.

Result

value  (D0) - The signed integer obtained from the string.
digits (D1) - The number of digits scanned from the string, plus one
              if there was a leading + or -.

Notes

This function is excluded from the C headers and is only
implemented for m68k CPUs.
The ARexx User's Reference Manual (1987) is incorrect.
The result registers listed above are the correct ones.
Registers A2-A7 and D2-D7 are preserved across the call.

Synopsis

LONG CVi2a(
         UBYTE * buffer,
         LONG value,
         UWORD digits );

Function

This function writes the digits of the signed 32-bit integer value
to the buffer given, including the terminating NUL character.
The function returns both the number of bytes written
and a pointer to the NUL character in the buffer.

Inputs

buffer (A0) - A pointer to the destination buffer.
value  (D0) - A signed 32-bit integer to generate the characters from.
digits (D1) - The max number of digits to write, including any sign
              but excluding the terminating NUL character.
              Zero means no limit.

Result

length  (D0) - The number of bytes written, excluding the terminating
               NUL character.
pointer (A0) - A pointer to the terminating NUL character.

Example

Setting value=-2000 and digits=3 will yield the string "-00".

Notes

If digits is less than the number of characters needed, the least
significant digits that fit will be written. Any sign needed will be
included.
This function is excluded from the C headers and is only
implemented for m68k CPUs.
Registers A2-A7 and D2-D7 are preserved across the call.

Synopsis

UBYTE * CVi2arg(
         LONG value );

Function

This function creates an argstring containing a string representation
of the signed 32-bit integer value given.
The argstring can be freed with DeleteArgstring().

Inputs

value  (D0) - A signed 32-bit integer to generate the characters from.

Result

pointer (D0, A0) - A pointer on the same format that CreateArgstring() returns.

Notes

This function is excluded from the C headers and is only
implemented for m68k CPUs.
The ARexx User's Reference Manual (1987) is incorrect.
There is no "digits" argument.
Registers A2-A7 and D2-D7 are preserved across the call.

Synopsis

VOID DeleteArgstring(
         UBYTE * argstring );

Function

Releases storage for a Rexx argument string using the allocation
information associated with its data pointer.

Inputs

argstring - Non-NULL pointer to the data of an allocated RexxArg,
            such as one returned by CreateArgstring(). It must not
            have been freed already.

Result

None.

Notes

Do not pass an ordinary C string or a pointer into the middle of
an argument string. The pointer becomes invalid after this call.

See also

CreateArgstring() LengthArgstring() ClearRexxMsg()

Synopsis

VOID DeleteRexxMsg(
         struct RexxMsg * packet );

Function

Frees the storage of a RexxMsg created with CreateRexxMsg().
Referenced argument strings and other resources are not freed.

Inputs

packet - Non-NULL RexxMsg returned by CreateRexxMsg(). The
         message must no longer be in use.

Result

None.

Notes

Wait for any outstanding reply before deleting a sent message.
Release argument strings owned by the caller with ClearRexxMsg()
before deleting the message. The function does not free strings
referenced by rm_CommAddr or rm_FileExt.

See also

CreateRexxMsg() ClearRexxMsg() DeleteArgstring()

Synopsis

BOOL FillRexxMsg(
         struct RexxMsg * msgptr,
         ULONG count,
         ULONG mask );

Function

Converts the first count entries of msgptr->rm_Args into allocated
Rexx argument strings. For entry i, bit i of mask selects the
input type: a set bit treats the field as a signed long integer;
a clear bit treats it as a pointer to a NUL-terminated C string.

Inputs

msgptr - RexxMsg whose rm_Args entries contain input values.
count  - Number of entries to convert, from 0 through MAXRMARG.
mask   - Type-selection bits for the first count entries. Bit i
         selects integer conversion when set and string copying
         when clear.

Result

TRUE if every selected entry is converted. FALSE if memory
allocation fails; newly allocated strings are then released and
the original rm_Args entries remain unchanged.

Notes

On success, the converted entries contain pointers to newly
allocated Rexx argument strings. A NULL string input remains
NULL. Original C strings are copied, not freed. Use
ClearRexxMsg() to release the converted argument strings.
Do not call this function again on already converted entries:
replacing their pointers does not release the previous strings.
Only the characters preceding the first NUL byte of a source C
string are copied.

Bugs

count is not checked against the rm_Args array or the local
conversion array. Values beyond their capacity cause
out-of-bounds accesses.

See also

ClearRexxMsg() CreateRexxMsg() CreateArgstring()

Synopsis

BOOL IsRexxMsg(
         struct RexxMsg * msgptr );

Function

Tests whether a message node carries the identity marker used by
this RexxSys library.

Inputs

msgptr - Non-NULL pointer to a readable message node.

Result

TRUE if the node's ln_Name pointer matches the RexxSys marker;
FALSE otherwise.

Notes

This is a pointer-identity test, not validation of an arbitrary
memory address or the contents of a complete RexxMsg structure.

See also

CreateRexxMsg()

Synopsis

ULONG LengthArgstring(
         UBYTE * argstring );

Function

Returns the stored byte length of a Rexx argument string. Unlike
strlen(), this function does not stop at an embedded NUL byte.

Inputs

argstring - Non-NULL pointer to the data of a valid RexxArg,
            such as one returned by CreateArgstring().

Result

Stored byte length, excluding the terminating NUL byte.

Notes

The argument must be a valid Rexx argument string, not an
ordinary NUL-terminated C string.

See also

CreateArgstring() DeleteArgstring()

Synopsis

VOID LockRexxBase(
         ULONG resource );

Function

Acquires the RexxSys library semaphore, waiting until it becomes
available.

Inputs

resource - Ignored by this implementation.

Result

None.

Notes

Release the semaphore with UnlockRexxBase() after accessing the
shared RexxSys state. Synchronization applies only to code using
the same semaphore.

See also

UnlockRexxBase()

Synopsis

ULONG StrcmpN(
         UBYTE * string1,
         UBYTE * string2,
         ULONG length );

Function

This function compares the strings for the specified number of
characters.

Inputs

string1 (A0) - A pointer to the first character of the first string.
string2 (A1) - Likewise for the second string.
length  (D0) - The number of characters to compare.

Result

test (D0) - -1 if the second string is less, 0 if equal, 1 if greater.
If one string ends it is considered less than a string that continues.
The CCR flags are updated according to the result.

Notes

This function is excluded from the C headers and is only
implemented for m68k CPUs.
The ARexx User's Reference Manual (1987) incorrectly says that 1 is
returned if the first string is greater.
Registers A2-A7 and D2-D7 are preserved across the call.

Synopsis

ULONG Strlen(
         UBYTE * string );

Function

This function returns the length of the provided ASCII string,
and sets the Z flag of the m68k CCR if the string is empty.

Inputs

string (A0) - A pointer to the first character of the ASCII string.

Result

length (D0) - The length of the ASCII string.
The CCR Z flag is set if the length is zero.

Notes

This function is excluded from the C headers and is only
implemented for m68k CPUs.
Registers A0, A2-A7, and D2-D7 are preserved across the call.

Synopsis

VOID UnlockRexxBase(
         ULONG resource );

Function

Releases the RexxSys library semaphore acquired with
LockRexxBase().

Inputs

resource - Ignored by this implementation.

Result

None.

Notes

The calling task must hold the corresponding lock acquired with
LockRexxBase(). Pair every successful acquisition with a release.

See also

LockRexxBase()