I’ve posted the updated slides from a talk I just presented about the PHP for IBM i Toolkit. The talk was given at a free virtual conference presented by the COMMON user group and was sponsored by BCD.
The slides are available on my “past presentations” page.
I’d like to hear how you are using the toolkit. Post comments here.
Some developers make a common mistake when calling a procedure in a service program using the PHP Toolkit for IBM i or any toolkit based on XMLSERVICE. It’s easy to supply the wrong procedure name, or the right name in the wrong case (upper/lower/mixed). Using this example of calling a procedure using the toolkit, we find the following (correct) program/procedure call:
|
1 2 |
$result = $conn->PgmCall('MYPGM', 'MYLIB', $params, $retParam, array('func'=>'myproc')); |
The procedure name ‘myproc’ must be given exactly as it is, not ‘MYPROC’ or ‘MyProc’, because under some circumstances the name may be case-sensitive.
|
1 |
DSPSRVPGM SRVPGM(MYLIB/MYPGM) DETAIL(*PROCEXP) |
The above command will return service program information, including the names of all procedure exports. For example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
Display Service Program Information Service program . . . . . . . . . . . . : MYPGM Library . . . . . . . . . . . . . . . : MYLIB Owner . . . . . . . . . . . . . . . . . : PROGRAMMER Service program attribute . . . . . . . : RPGLE Detail . . . . . . . . . . . . . . . . . : *PROCEXP Procedure Exports: Procedure Name ARGOPT myproc *NO orderHeader *NO |
This service program contains two procedures: ‘myproc’ and ‘orderHeader’. Thus, to call the former, we’d supply array(‘func’=>’myproc’) in the PgmCall method. If we wanted to call the second procedure, we’d use array(‘func’=>’orderHeader’), observing case sensitivity, which often matters (a topic for another day).
Update: a recording of the webinar is available to all registrants. See the link below to register.
——–
I’ll be presenting a free webinar, “How to ensure speedy PHP applications on IBM i,” on Thursday, June 11, 2015, at 1pm Eastern/New York time. The webinar is sponsored by BCD. Registration and more information: http://www.bcdsoftware.com/bcdtracks/webinars/ondemand/php-performance-alan.htm
“Our process now runs 30-50% faster, thanks to one tip from Alan’s presentation.”
— Mike Meszaros, Software Developer, Specialty Pipe & Tube
Calling procedures in RPG service programs, including getting the return value, is a powerful feature of the PHP Toolkit. The sample script below demonstrates how it’s done.
Note: Make sure your procedure name is 100% correct. It is case-sensitive. If you get an error, run the following command (replacing LIBNAME/PGMNAME with your library and program names) and look for your procedure name in the output. The command:
DSPSRVPGM SRVPGM(LIBNAME/PGMNAME) DETAIL(*PROCEXP)
The example below includes ‘boilerplate’ code to show best practices for connecting to the toolkit and checking for a successful connection. The illustration of how to call a procedure is in the second half.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 |
<?php require_once('ToolkitService.php'); // connect to toolkit using DB2 credentials (can also leave blank for default authority) try { $conn = ToolkitService::getInstance('*LOCAL', 'MYUSER', 'MYPASS'); } catch (Exception $e) { // Determine reason for failure. // Probably database authentication error or invalid or unreachable database. $code = $e->getCode(); $msg = $e->getMessage(); switch ($code) { case 8001: // "Authorization failure on distributed database connection attempt" // Usually means a wrong DB2 user or password echo 'Could not connect due to wrong user or password.'; break; case 42705: echo 'Database not found. Try WRKRDBDIRE to check.'; break; default: echo 'Could not connect. Error: ' . $code . ' ' . $msg; break; } //(switch) die; // couldn't connect...handle this however you wish } //(try/catch) // set stateless mode for easy testing (no 'InternalKey' needed). // (setOptions() introduced in v1.4.0) $conn->setOptions(array('stateless'=>true)); /* If you wish to test this script but you don't have a real service program, * use parseOnly and parseDebugLevel as shown below. * No program will be called and you'll get your original values back. * Simply uncomment the next line to try this great testing feature of the toolkit. */ //$conn->setOptions(array('parseOnly'=>true, 'parseDebugLevel'=>1)); // define several input/output params $params = []; // start with empty array $params[] = $conn->AddParameterChar('in', 1,'Division', 'DIV', 'A'); $params[] = $conn->AddParameterChar('in', 6,'Product', 'PROD', '123456'); $params[] = $conn->AddParameterPackDec('both', 7, 2, 'Quantity', 'QTY', '4.53'); $params[] = $conn->AddParameterZoned('out', 5, 2, 'Price', 'PRICE', '0'); // define a procedure return param. Can be any type, even a data structure $retParam = $conn->AddParameterInt32('out', '4-byte int', 'MYRESULT', '13579'); /* Call service program procedure. * In this example, assume your program is MYLIB/MYPGM and has a procedure/function 'myproc' * (procedure name is case-sensitive). * Note: specify optional procedure name in parameter 5, an array with associative index 'func'. */ $result = $conn->PgmCall('MYPGM', 'MYLIB', $params, $retParam, array('func'=>'myproc')); if (!$result) { echo 'Error calling program. Code: ' . $conn->getErrorCode() . ' Msg: ' . $conn->getErrorMsg(); } echo 'Called program successfully.<BR><BR>'; echo 'Input/output params: QTY: ' . $result['io_param']['QTY'] . ' PRICE: ' . $result['io_param']['PRICE'] . '<BR>'; echo 'Procedure return param MYRESULT: ' . $result['retvals']['MYRESULT']; /* The above will output something like: Called program successfully. Input/output params: QTY: 4.53 PRICE: 0.00 Procedure return param MYRESULT: 13579 */ |
For more information on the toolkit, see our toolkit information page or get in touch.