This chapter contains a list of functions in pcmif, the Perl extension to Oracle Communications Billing and Revenue Management (BRM) Portal Communications Module (PCM) library, with links to the description of each function in the library.
For guidelines on using the Perl extensions to create applications, see "Creating Client Applications by Using Perl PCM" in BRM Developer's Guide.
For sample Perl scripts using pcmif, see "Example Perl Scripts".
Table 4-1 list the connection function perl extensions to the PCM libraries.
Table 4-1 Connection Functions
| Function | Description |
|---|---|
|
Closes the given PCM context, disconnects from BRM, and frees memory associated with the context. |
|
|
Connects to BRM by using PCM_CONNECT. |
|
|
Opens a PCM context to BRM by using PCM_CONTEXT_OPEN. |
|
|
Obtains the session ID set after login as a printable POID and returns it as a string. |
|
|
Obtains the user ID set after login as a printable POID and returns it as a string. |
|
|
Returns the time from the pin_virtual_time function, which is used to change time in BRM. |
Table 4-2 list the error-handling function perl extensions to the PCM libraries.
Table 4-2 Error-Handling Functions
| Function | Description |
|---|---|
|
Deletes a previously created error buffer from memory. |
|
|
Returns a static string with a printable representation of the error buffer. |
|
|
Checks for errors and returns the integer value of the error code in the error buffer. |
|
|
Creates an empty error buffer structure and returns a pointer to it. |
|
|
Executes a printf of the printable representation of the error buffer. |
|
|
Sets an error buffer. |
Table 4-3 list the flist conversion function perl extensions to the PCM libraries.
Table 4-4 list the PCM opcode function perl extensions to the PCM libraries.
This section describes sample Perl scripts.
This sample script performs the following actions:
It connects to BRM using the login information in the parameters set in the Config section. The pin.conf file only needs a dummy user ID entry.
If there is an argument, it uses that as the POID ID of the data object to read.
If there is no argument, it uses POID ID 1 as the default.
It then reads an object with the POID ID using PCM_OP_READ_OBJ and displays the resulting flist.
#The first line of the Perl script.
#!/BRM_Home/perl/bin/perl
#
#Test a readobj of /data N (defaults to 1).
#Use the following two lines to specify the directory of the pcmif
#files and that you are using the pcmif module.
use lib '.' ;
use pcmif;
# Config section
# Uses pcm_context_open(), so requires pin.conf with userid only
# Set the login information.
$LOGIN_DB = "0.0.0.1";
$LOGIN_NAME = "root.0.0.0.1";
$LOGIN_PASSWD = "password";
$CM_HOST = "somehost";
# Setup and connect
# Create an ebuf for error reporting.
$ebufp = pcmif::pcm_perl_new_ebuf();
# Use a "here" document to assign an flist string to a variable.
$f1 = <<"XXX"
0 PIN_FLD_POID POID [0] $LOGIN_DB /service/pcm_client 1 0
0 PIN_FLD_TYPE ENUM [0] 1
0 PIN_FLD_LOGIN STR [0] "$LOGIN_NAME"
0 PIN_FLD_PASSWD_CLEAR STR [0] "$LOGIN_PASSWD"
0 PIN_FLD_CM_PTR STR [0] "ip $CM_HOST 11960"
XXX
;
# Use the string-to-flist conversion function to parse the flist string
# that contains the login information and use it to open a PCM #context.
$login_flistp = pcmif::pin_perl_str_to_flist($f1,
$LOGIN_DB, $ebufp);
# Check for errors and print the error report.
if (pcmif::pcm_perl_is_err($ebufp)) {
print "flist conversion failed\n";
pcmif::pcm_perl_print_ebuf($ebufp);
exit(1);
}
# Open a PCM context.
$pcm_ctxp = pcmif::pcm_perl_context_open($login_flistp,
$db_no, $ebufp);
# Check for errors and print the status of the action.
if (pcmif::pcm_perl_is_err($ebufp)) {
pcmif::pcm_perl_print_ebuf($ebufp);
exit(1);
} else {
$my_session = pcmif::pcm_perl_get_session($pcm_ctxp);
$my_userid = pcmif::pcm_perl_get_userid($pcm_ctxp);
print "back from pcmdd_context_open()\n";
print " DEFAULT db is: $db_no \n";
print " session poid is: ", $my_session, "\n";
print " userid poid is: ", $my_userid, "\n";
}
# See if we should default to 1, or get a number
if ($#ARGV >= 0) {
$obj_id = $ARGV[0];
} else {
$obj_id = 1;
}
# Build an flist.
$f1 = <<"XXX"
0 PIN_FLD_POID POID [0] $db_no /data $obj_id 0
XXX
;
# Convert the flist you built from a string to the flist format.
$flistp = pcmif::pin_perl_str_to_flist($f1, $db_no, $ebufp);
# Check for errors and print the error report.
if (pcmif::pcm_perl_is_err($ebufp)) {
print "flist conversion failed\n";
pcmif::pcm_perl_print_ebuf($ebufp);
exit(1);
}
# Convert the flist to a printable string and print it.
$out = pcmif::pin_perl_flist_to_str($flistp, $ebufp);
print "IN flist is:\n";
print $out;
# Perform a PCM operation to read an object and assign the result
# to a variable. Check for errors and print the error report.
$out_flistp = pcmif::pcm_perl_op($pcm_ctxp, "PCM_OP_READ_OBJ", 0,
$flistp, $ebufp);
if (pcmif::pcm_perl_is_err($ebufp)) {
print "robj failed\n";
pcmif::pcm_perl_print_ebuf($ebufp);
exit(1);
}
# Convert the flist for the object you read to a printable string and print it.
$out = pcmif::pin_perl_flist_to_str($out_flistp, $ebufp);
print "OUT flist is:\n";
print $out;
# Close the PCM context. Check for errors and print the error report.
pcmif::pcm_context_close($pcm_ctxp, 0, $ebufp);
if (pcmif::pcm_perl_is_err($ebufp)) {
print "BAD close\n",
pcmif::pcm_perl_ebuf_to_str($ebufp), "\n";
exit(1);
}
exit(0);
The following example is used to set up an account with a service of type /service/ip with the user name testterm01 (for a test script). It checks for the existence of the service, and exits if the service is found. Otherwise, it finds the /deal needed for ”IP Basic” (a standard default) and then creates the /account and /service/ip objects by using PCM_OP_CUST_COMMIT_CUSTOMER.
#!/BRM_Home/perl/bin/perl # This is the directory for the pcmif.so and pcmif.pm files. # For most usage this is not needed, since they will be obtained # from the default directory (builtin to perl/BRM_Home/<vers>/lib). use lib '.' ; # The key - You MUST include this to indicate that you are using # the pcmif extension. use pcmif; # The "pcmif::" prefix is a class prefix, meaning that the # function "pcm_perl_new_ebuf()" is from the package/class #"pcmif". # # Get an ebuf for error reporting. # $ebufp = pcmif::pcm_perl_new_ebuf(); # Do a pcm_connect(), $db_no is a return. $pcm_ctxp = pcmif::pcm_perl_connect($db_no, $ebufp); # Convert an ebuf to a printable string. $ebp1 = pcmif::pcm_perl_ebuf_to_str($ebufp); # Check for errors. Always do this. if (pcmif::pcm_perl_is_err($ebufp)) { pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } else { print "back from pcm_connect()\n"; print " DEFAULT db is: $db_no \n"; } # NOTE: The following convention ($DB_NO) was established # for use with testnap, to substitute the database number # into a printed flist as it was parsed into testnap. # We follow the text convention, but we let perl # do the substitution via this variable (in upper case). # NOTE: The flist parse should also perform # this substitution since it gets fed $db_no. # for testnap convention. $DB_NO = $db_no; # Use a "here" document to build an flist string into # a variable. This flist will then be parsed and # used in a pcm_op. # # search to see if /service/ip "testterm01" is already created $f1 = <<"XXX" 0 PIN_FLD_POID POID [0] $DB_NO /search 236 0 0 PIN_FLD_PARAMETERS STR [0] "ip" 0 PIN_FLD_ARGS ARRAY [1] 1 PIN_FLD_LOGIN STR [0] "testterm01" 0 PIN_FLD_RESULTS ARRAY [0] 1 PIN_FLD_POID POID [0] 0.0.0.0 0 0 1 PIN_FLD_LOGIN STR [0] "" XXX ; $flistp = pcmif::pin_perl_str_to_flist($f1, $db_no, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "flist conversion to check for testterm01 failed\n"; pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } $out_flistp = pcmif::pcm_perl_op($pcm_ctxp, "PCM_OP_SEARCH", 0, $flistp, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "SEARCH for testterm01 failed\n"; pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } # # Check if "testterm01" is there. If it is you do not # have to recreate. # $out = pcmif::pin_perl_flist_to_str($out_flistp, $ebufp); # XXX warning, no error check pcmif::pin_flist_destroy($flistp); pcmif::pin_flist_destroy($out_flistp); # We converted the output flist into $out above, # then cleaned the flist objects up. Now we use # a perl string matching operator to look for the # user id we want. # if ($out =~ "testterm01") { print "testterm01 already exists\n" ; print $out; exit(0); } print "XXX testterm01 does NOT exist\n" ; # # First we need the poid of the deal - use "IP Basic". # $f1 = <<"XXX" 0 PIN_FLD_POID POID [0] $DB_NO /search 223 0 0 PIN_FLD_ARGS ARRAY [1] 1 PIN_FLD_NAME STR [0] "IP Basic" 0 PIN_FLD_RESULTS ARRAY [0] 1 PIN_FLD_POID POID [0] 0.0.0.0 0 0 XXX ; # $flistp = pcmif::pin_perl_str_to_flist($f1, $db_no, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "flist conversion to search for deal failed\n"; pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } $out_flistp = pcmif::pcm_perl_op($pcm_ctxp, "PCM_OP_SEARCH", 0, $flistp, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "SEARCH for deal failed\n"; pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } $out = pcmif::pin_perl_flist_to_str($out_flistp, $ebufp); # XXX warning, no error check pcmif::pin_flist_destroy($flistp); pcmif::pin_flist_destroy($out_flistp); if ($out !~ "/deal") { print "no deal found \n" ; print $out; exit(1); } # # The deal poid (which will be <db> /deal <id> <rev>) # is isolated with index().Then the rest of the line # (containing the id...) goes into deal_poid, which is # trimmed by saving the matching pattern # (ie the id number) and substituting the saved pattern # (ie just the numbers) for the rest of the line. # $deal_at = index($out, "/deal"); $deal_poid = substr($out, $deal_at + 6); $deal_poid =~ s|([0-9][0-9]*) .*|$1| ; print "deal poid is ", $deal_poid, "\n"; # # now we fill in an flist for COMMIT_CUSTOMER # $f1 = <<"XXX" 0 PIN_FLD_POIDPOID [0] $DB_NO /account 0 0 PIN_FLD_ACCOUNT_OBJPOID [0] $DB_NO /account 0 0 PIN_FLD_AAC_ACCESS STR [0] "setup.fm_term" 0 PIN_FLD_AAC_SOURCE STR [0] "setup.fm_term" 0 PIN_FLD_AAC_VENDOR STR [0] "setup.fm_term" 0 PIN_FLD_AAC_PACKAGE STR [0] "setup.fm_term" 0 PIN_FLD_AAC_PROMO_CODE STR [0] "setup.fm_term" 0 PIN_FLD_AAC_SERIAL_NUM STR [0] "setup.fm_term" 0 PIN_FLD_BILLINFOARRAY [1] 1 PIN_FLD_BILL_TYPEENUM [0] 0 1 PIN_FLD_CURRENCYUINT [0] 840 0 PIN_FLD_PAYINFOARRAY [1] 1 PIN_FLD_NAMEINFO_INDEXUINT [0] 1 0 PIN_FLD_NAMEINFOARRAY [1] 1 PIN_FLD_SALUTATION STR [0] "Mr." 1 PIN_FLD_LAST_NAME STR [0] "testterm01" 1 PIN_FLD_FIRST_NAME STR [0] "testterm01" 1 PIN_FLD_MIDDLE_NAME STR [0] "x" 1 PIN_FLD_TITLE STR [0] "title" 1 PIN_FLD_COMPANY STR [0] "company" 1 PIN_FLD_ADDRESS STR [0] "address" 1 PIN_FLD_CITY STR [0] "Cupertino" 1 PIN_FLD_STATE STR [0] "CA" 1 PIN_FLD_ZIP STR [0] "95014" 1 PIN_FLD_COUNTRY STR [0] "USA" 1 PIN_FLD_EMAIL_ADDR STR [0] "email_addr" 1 PIN_FLD_CONTACT_TYPE STR [0] "contact_type" 0 PIN_FLD_SERVICESARRAY [1] 1 PIN_FLD_SERVICE_OBJPOID [0] $DB_NO /service/ip 0 1 PIN_FLD_LOGIN STR [0] "testterm01" 1 PIN_FLD_PASSWD_CLEAR STR [0] "testterm01" XXX ; # # To avoid quotation problems in the above here document, # the deal is appended via ".". # $f1 = $f1 . "1PIN_FLD_DEAL_OBJ POID [0] $DB_NO /deal $deal_poid" ; print "flist is now\n"; print $f1; $flistp = pcmif::pin_perl_str_to_flist($f1, $db_no, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } $out_flistp = pcmif::pcm_perl_op($pcm_ctxp, "PCM_OP_CUST_COMMIT_CUSTOMER", 0, $flistp, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "BAD op: PCM_OP_CUST_COMMIT_CUSTOMER\n"; pcmif::pcm_perl_print_ebuf($ebufp); exit(1); } $out = pcmif::pin_perl_flist_to_str($out_flistp, $ebufp); print "OUT flist is \n" ; print $out; pcmif::pin_flist_destroy($flistp); pcmif::pin_flist_destroy($out_flistp); pcmif::pcm_context_close($pcm_ctxp, 0, $ebufp); if (pcmif::pcm_perl_is_err($ebufp)) { print "BAD close\n", pcmif::pcm_perl_ebuf_to_str($ebufp), "\n"; exit(1);
This function closes the given PCM context, disconnects from BRM, and frees memory associated with the context. If a context is no longer needed, make sure you close it.
For more information, see "PCM_CONTEXT_CLOSE".
A reference to an open PCM context.
Defines how to close the connection.
The standard option is to completely close the connection by passing in 0. However, if you fork a process, make sure that the process which does not make PCM calls any more (usually the child process) closes all open file descriptors (FDs). You can do this by passing 1 as the value of how, which is PCM_CONTEXT_CLOSE_FD_ONLY in pcm.h. This allows the child process (in most cases) to close the FDs without closing the PCM connection in the parent process that spawned it. If you want the child process to continue making PCM calls, open another PCM connection.
A reference to an error buffer obtained through pcm_perl_new_ebuf.
This function connects to BRM by using PCM_CONNECT.
The variable for the database number.
A reference to an error buffer obtained through pcm_perl_new_ebuf.
Returns an opaque reference to the PCM context and sets the database number to db_no if the function is successful.
This function opens a PCM context to BRM by using PCM_CONTEXT_OPEN.
A reference to the login flist. The login flist must have a dummy PIN_FLD_POID, a valid login type in PIN_FLD_TYPE, the PIN_FLD_LOGIN, and any other fields required for the given type, usually PIN_FILD_PASSWD_CLEAR. Connection Manager (CM) is declared in the pin.conf file or by one or more PIN_FLD_CM_PTR fields in the login flist.
The variable for the database number.
A reference to an error buffer obtained through pcm_perl_new_ebuf.
Returns an opaque reference to the PCM context and sets the database number to db_no if the function is successful.
This function deletes a previously created error buffer from memory.
This function returns a static string with a printable representation of the error buffer.
This function obtains the session ID set after login as a printable POID and returns it as a string.
This function obtains the user ID set after login as a printable POID and returns it as a string.
This function checks for errors and returns the integer value of the error code in the error buffer.
This function creates an empty error buffer structure and returns a pointer to it.
This function performs the indicated PCM operation.
A reference to an open PCM context.
The PCM opcode that indicates the operation to be performed. op may be a number or symbolic opcode name, as long as it is known to BRM. For example, you can use 354 or PCM_OP_TERM_IP_DIALUP_AUTHORIZE.
For a list of opcode names, see PCM opcode libraries.
A flag for the opcode. See the opcode description for information on the flags each opcode supports. Most opcodes take no flag, which is input as (int32) 0.
A reference to the input flist.
For the input flist specifications, see PCM opcode libraries.
A reference to the error buffer.
Returns a reference to the resulting flist if the function is successful. Returns NULL if there is a serious error.
Note:
You have to explicitly destroy both the input and return flists. They are not automatically deleted.This function uses individual-style ebuf error handling. This means the application must explicitly test for an error condition recorded in the error buffer before making other calls to the BRM application programming interface (API).
The following error codes returned from PCM_OP indicate an error in the Portal Communication Protocol (PCP) transmission:
PIN_ERR_BAD_XDR
PIN_ERR_STREAM_EOF
PIN_ERR_STREAM_IO
PIN_ERR_TRANS_LOST
PIN_ERR_CM_ADDRESS_LOOKUP_FAILED
Important:
If you see one of these errors, close the context where the error occurred and open a new context. The output flist is undefined, but the input flist is still valid.This function executes a printf of the printable representation of the error buffer.
This function deletes an opaque flist.
This function sorts the specified flist using PIN_FLIST_SORT.
A reference to the flist being sorted. The flist normally is an array and the sorting is performed on elements of the array. Each element of the array can be a list of fields; it is those fields that get sorted.
A list of fields in each element in flistp to use as sort fields. Elements in flistp are sorted in this order. If the value of this parameter is NULL, PIN_ERR_BAD_ARG is returned.
Reverses the order in which the flist is sorted.
Compares nonexistent fields to existing fields.
For detailed information, see "PIN_FLIST_SORT".
A reference to the error buffer.
This routine uses series-style ebuf error handling. Applications can call any number of series-style ebuf API routines by using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors.
This function converts an opaque flist into a printable string representation.
For more information, see "PIN_FLIST_TO_STR".
Returns the flist in a printable string format if the function is successful. Returns NULL if the function fails.
This routine uses series-style ebuf error handling. Applications can call any number of series-style ebuf API routines by using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors.
For more information, see "Understanding API Error Handling and Logging" in BRM Developer's Guide.
This function converts a printable flist into an opaque flist and returns a reference to the flist. If the flist uses the string ’$DB_NO' for the database in the POID type fields, the value of db_no is substituted. In Perl, it is easier to set a variable $DB_NO and let Perl substitute the ”DB_NO” if the flist is defined using here documents.
A reference to the destination string containing an flist in printable format.
A reference to the database number. Must be a string containing a BRM database number in dotted decimal format that is used to set the default database for parsing the flist.
A reference to the error buffer.
Returns the reference to the flist created from the input string if the function is successful. Returns NULL if the function fails.
This function uses series-style ebuf error handling. Applications can call any number of series-style ebuf API routines using the same error buffer and check for errors only once at the end of the series of calls. This makes manipulating flists and POIDs much more efficient because the entire logical operation can be completed and then tested once for any errors.
For more information, see "Understanding API Error Handling and Logging" in BRM Developer's Guide.
This function returns the time from the pin_virtual_time function, which is used to change time in BRM. You use this function for testing time-sensitive functions in BRM without affecting the system clock.
For more information, see "pin_virtual_time" in BRM Developer's Guide.
This function has no parameters. However, for time offsets to take effect, there must be an entry for pin_virtual_time in the pin.conf file.
Returns the time as a UNIX style time value: the number of seconds since 00:00:00 UTC, January 1, 1970.
This function sets an error buffer.
A reference to the error buffer to be set.
The location of an error, which is one of the PIN_ERRLOC_xxx, where xxx indicates the subsystem that issued the error.
For details, see "pin_set_err".
One of the four classes of error PIN_ERRCLASS_xxx.
For details, see "pin_set_err".
One of the system error messages PIN_ERR_xxx.
For details, see "pin_set_err".
Set this field to 0 or to the applicable PIN_FLD_xxx.
Set this field to 0 or to the record ID of the array element where the error occurred.
Reserved. Set this field to 0 or to a value chosen to provide further information about the specific error.