Next Meeting: Sat, TBD
Meeting Directions

Be a Member Join SCOUG

20 Most Recent Documents
Search Archives
Index by date, title, author, category.

Features:

Mr. Know-It-All
Ink
Download!

Home

Email Lists

SIGs (Internet, General Interest, Programming, Network, more..)

Online Chats

Business

Past Presentations

Credits

Submissions

Contact SCOUG

Copyright SCOUG

SCOUG was there!

SCOUG, Warp Expo West, and Warpfest are trademarks of the Southern California OS/2 User Group. OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.

Introduction

Review of Part 1

Using C to Provide Enhanced Capabilities for REXX programs

Using C To Enhance REXX

Provide additional functions to REXX programs

Create Database, Communication, and Network interfaces

Provide PM GUI functionality

Provide advanced OS features (threads, semaphores, IPC)

Online Reference Materials

OS/2 Prodcedures Language 2/REXX (comes with Warp)

REXX Program Reference or Object REXX Programming Guide (comes with Developer's Toolkit and Visual Age C++)

Procedures Language 2/REXX User's Guide (REXXBASE.INF)

The Variable Pool Interface

REXX variables are stored as name-value string pairs

Variable Pool interface allows C program to set and fetch values

Fetch either by explicit name or enumeration

Multiple requests can be made in a single call to RexxVariablePool

Two types of name specification: Symbolic and Direct

The SHVBLOCK Structure

Used to create a linked list of requests

Definition: typedef struct _SHVBLOCK { struct _SHVBLOCK *shvnext; /* pointer to the next block */ RXSTRING shvname; /* name buffer */ RXSTRING shvvalue; /* value buffer */ ULONG shvnamelen; /* length of the name */ ULONG shvvaluelen; /* length of the value */ UCHAR shvcode; /* operation code */ UCHAR shvret; /* return code flags s*/ } SHVBLOCK; typedef SHVBLOCK *PSHVBLOCK;

Operation Codes and Return Flags

Operation codes:

RXSHV_SYSET

set

RXSHV_SYFETCH

fetch

RXSHV_SYDRO

drop

RXSHV_NEXTV

enumerate variables

RXSHV_PRIV

fetch private information

Return flags:

RXSHV_OK

RXSHV_NEWV

RXSHV_LVAR

RXSHV_TRUNC

The RexxVariablePool Function

Function prototype: APIRET APIENTRY RexxVariablePool(PSHVBLOCK);

Single argument - Pointer to 1st SHVBLOCK in list

Return code is aggregate of all return flags in list

The Subcommand Interface

Allows REXX program to use custom defined commands

Subcommand handler functions can be in either the executable or a DLL

Subcommand handler functions must be registered before use

Identified by "environment name" parameter in RexxStart

Many can be registered, but only one is effect

Subcommand Handler Functions

ALL subcommand handler functions MUST be defined as follows: ULONG EXPENTRY MySubcommandHandler( PRXSTRING prxCommand, /* cmd line */ PUSHORT pusFlags, /* ret flags */ PRXSTRING prxReturn ); /* ret string */

Register with RexxRegisterSubcomExe or RexxRegisterSubcomDll

Subcommand handler function must parse command line

External Functions

Extends the number of functions available to a REXX program

External functions can be in either the executable or a DLL

If packaged in a DLL, can form an API to another subsystem

REXX program does NOT have to started via RexxStart

External functions must be registered before use

No limit to number of functions that can be made available

External Function Definition

ALL external functions MUST be defined as follows: ULONG EXPENTRY MyExtFunction( PSZ pszName, /* function name */ ULONG ulArgv, /* arg count */ RXSTRING rxArgc, /* arg values */ PSZ pszQueueName, /* queue name */ PRXSTRING prxReturn ); /* ret value */

Register with RexxRegisterFunctionExe or RexxRegisterFunctionDll

If used in a DLL, use EXPORTS statements to provide case insensitivity

Note that arguments are parsed by the REXX interpreter

Creating An API For REXX Programs

Create a DLL containing a function to load the other functions: static PSZ pszRxFncTbl[] = { "OHSThis", "OHSThat", "OHSTheOtherThing"}; ULONG EXPENTRY LoadOHSFuncs (PSZ pszName, ULONG ulArgc, RXSTRING rxArgv[], PSZ pszQueue, PRXSTRING prxReturn); { LONG lEntries, i; prxReturn->strlength = 0; if (ulArgc > 0) return 40; /* s/b no args s/b passed */ lEntries = sizeof(pszRxFncTable)/sizeof(PSZ); for (i = 0; i<lEntries; i++) { RexxRegisterFunctionDll(pszRxFncTbl[i], "OHSDLL", pszRxFncTbl[i]); } return 0; }

Using the API in a REXX Program

First, add the loader function: /* rexx */ call RxFuncAdd "LoadOHSFuncs", "OHSDLL", "LoadOHSFuncs"

Then, invoke it: call LoadOHSFuncs Note the parallel to loading the REXXUTIL.DLL functions

Parameter Handling In External Functions

REXX always passes the value of a named variable used as an argument

To pass the NAME of a stem or return variable, enclose it in quotes

In the external function, use RexxVariablePool to fetch/set values

Stem variables and the "stem.0" convention

Halt and Trace Interface

RexxSetHalt raises a HALT condition in a running REXX program

RexxSetTrace turns on interactive debug mode

RexxResetTrace turns off interactive debug mode

Use in lieu of RXHLT and RXTRC exits

Multiple threads are implied - TID and PID must be known

Multiple Threads of REXX

Creating a multiple thread framework

External functions for transferring variable values across pools

External function wrappers for semaphores and other IPC facilities

Managing storage in the framework application