ptg 332 Chapter 13 PHP in WebSphere sMash Login Extension name: zero.php.LoginServiceExtension This sub-system provides the ability to log into a WebSphere sMash application program- matically. This can be used for system-level processing that needs to occur without user interac- tion (see Table 13.13). Table 13.12 CSFT Functions Function Description csrf_protected_form_field Creates a hidden form field that contains the CSRF token to be verified against the submission URI. Arguments: String uri—URI to be verified against CSRF. csrf_protected_uri Validates a UR I i s po in ti ng to t he or ig in at in g s er ver. Arguments: String uri—URI to be verified against CSRF. Table 13.13 Login Service Functions Function Description zero_login Logs in a user programmatically. Arguments: String username—Username to be authenticated. String password—Password for the user to be authenticated. zero_logout Logs out current user. No arguments defined for this method. Database Access Extension name: zero.php.QueryExtension This subsystem provides methods for accessing relational data sources. There are functions are broken down by: General, Query, Results, and Transactions. Database General Functions The following functions shown in Table 13.14 illustrate common data functions available for database data inspection. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 333 Table 13.14 Database General Functions Function Description dataIsValid data_is_valid Validates i f m an ag er h as co nfi gu ra ti on t ha t c an connect t o a database. Arguments: Manager mgr—DataSource manager to use. Returns: True if successfully connected to the database; false otherwise. dataLastError data_last_error Returns information about the last error. Returns: Map of last error, or NULL if no previous error. Keys in map are: type—“WARNING”, “SEVERE”, or “FATAL” functionName—Function causing error. message—Error message. dataManager dataNewManager data_manager data_new_manager Creates a new manager from a DataSource. The DataSource is indicated in one of two ways. The first way is to pass a resource that is returned from the dataSource API. The sec- ond way is to pass a string key that corresponds to a set of database parameters in the zero.config file. Arguments: DataSource resource or String dataSourceKey. Returns: Manager—Handle to the DataSource Manager. Download from www.wowebook.com ptg 334 Chapter 13 PHP in WebSphere sMash Database Query Functions Table 13.15 shows the functions used to perform database queries. Table 13.14 Database General Functions Function Description dataSource dataNewDataSource data_new_data_source data_source Creates and returns a DataSource of the given type. The type argument has three possible meanings, which are tested in the order shown. As soon as one of the mechanisms is suc- cessful at creating a DataSource, the function returns it. The type name has been previously registered with an IData- SourceProvider instance. See DataSourceFactory. registerProvider() for details. The type name is the fully qualified class name of a Data- Source implementor. The class will be instantiated with the default constructor, and the params will be set on the created DataSource object. Note that parameter keys are expected to map one-to-one with setter methods on the object. The type name, when appended to the string “zero.data.php.datasource”, forms a fully qualified class name of an IDataSourceProvider implementor. The IData- SourceProvider will be instantiated and registered with the type name. Arguments: String type—The DataSource type to create. Array params—List of parameters to pass into the Data- Source constructor. Returns: DataSource—DataSource instance, or NULL if fail to create new DataSource. dataStringAsByteArray data_string_as_byte_array bytes Returns the string argument as a string data resource. This kind of resource is used in situations where a BLOB is expected by the SQL engine. Arguments: String string—Source string to be processed as Blob. Returns: Array—Byte string to be treated as Blob by Database. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 335 Table 13.15 Database Query Functions Function Description dataExec data_exec Executes any SQL statement. SELECT operations are handled by queryArray, while all other operations are handled by update. Arguments: Manager mgr—DataSource manager to use. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Result whose type depends on the SQL statement used. For SELECT, an array of values. For others, an int indicating the number of rows altered. Value m ay be NU LL o n i nvalid p ar am et er s, or fa lse i f a n e rr or occurs. dataExecOpt data_exec_opt An optimized form of the exec API that behaves like query- First for SELECT statements and updateMany for other state- ments. Arguments: Manager mgr—DataSource manager to use. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Result whose type depends on the SQL statement used. For SELECT, a map of key/value pairs matching selection requests. For others, an array of ints indicating the number of rows altered. Value m ay be NU LL o n i nvalid p ar am et er s, or fa lse i f a n e rr or occurs. Download from www.wowebook.com ptg 336 Chapter 13 PHP in WebSphere sMash Table 13.15 Database Query Functions Function Description dataInsert data_insert Executes UPDATE and INSERT statements and returns gener- ated column values. The values of the generated keys are returned as strings that can be coerced to another type if needed. Arguments: Manager mgr—DataSource manager to use. String sql—SQL statement to process, with optional ‘?’ tokens. Array columns—Columns that contain generated keys. Array params—Parameters to use in SQL token replacement. Returns: The generated keys as strings, or false on error. dataExec data_exec Executes any SQL statement. SELECT operations are handled by queryArray, while all other operations are handled by update. Arguments: Manager mgr—DataSource manager to use. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Result whose type depends on the SQL statement used. For SELECT, an array of values. For others, an int indicating the number of rows altered. Value m ay be NU LL o n i nvalid p ar am et er s, or fa lse i f a n e rr or occurs. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 337 Table 13.15 Database Query Functions Function Description dataExecOpt data_exec_opt An optimized form of the exec API that behaves like query- First for SELECT statements and updateMany for other statements. Arguments: Manager mgr—DataSource manager to use. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replace- ment. Returns: Result whose type depends on the SQL statement used. For SELECT, a map of key/value pairs matching selection requests. For others, an array of ints indicating the number of rows altered. Value m ay be NU LL o n i nvalid p ar am et er s, or fa lse i f a n error occurs. dataQuery data_query Executes an SQL query (SELECT) and uses the result han- dler to create the return value. The result handler can have one of two forms, which are listed next. PHP callback function—Indicated by passing the function name. PHP ResultHandler resource. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. ResultHandler handler—Custom callback or resultHandler referenced from dataNewResultHandler call. Array params—Parameters to use in SQL token replacement. Returns: Results from ResultHandler processing. Download from www.wowebook.com ptg 338 Chapter 13 PHP in WebSphere sMash Table 13.15 Database Query Functions Function Description dataQueryArray data_query_array Executes a SQL query (SELECT) and returns an array of results where each element represents a single row. The rows themselves are key/value maps. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Array of result rows, containing map of column names and values. dataQueryArrayByFactory data_query_array_by_factory Executes a SQL query and uses the factory callback function to create the return value. The callback function will be called once per row. The result of each callback will be placed in an array and returned to the caller of this API. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Callback factory—Class with callback function to process ResultSet rows. Array params—Parameters to use in SQL token replacement. Returns: Array of result rows, containing map of column names and values. dataQueryFirst data_query_first Executes a SQL query and returns the first result row as a map. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Map of column names and values. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 339 Table 13.15 Database Query Functions Function Description dataQueryIterator data_query_iterator Executes a SQL query and returns an Iterator resource. The Iterator can be manipulated using the dataIterator APIs. Each iterated element represents a single row from the query result. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Iterator of maps of results row. dataQueryIteratorByFactory data_query_iterator_by_ factory Executes a SQL query and uses the factory callback function to create the return value as an Iterator. The callback must be called “callback,” take a single ResultSet argument, and whose response will be returned to the initial caller as the result. The callback is called once per resultset record. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Callback callback—Function to preprocess result record from query. Array params—Parameters to use in SQL token replacement. Returns: Iterator of return values from callback function Table 13.15 Database Query Functions Function Description dataQueryFirstByFactory data_query_first_by_factory Executes a SQL query and uses the factory callback function to create the return value. The result of the query will contain at most one row. The callback function will be called exactly once. The callback must be called “callback,” take a single ResultSet argument, and whose response will be returned to the initial caller as the result. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Callback callback—Function to pre-process the result record from a query. Array params—Parameters to use in SQL token replacement. Returns: Return value from callback function. Download from www.wowebook.com ptg 340 Chapter 13 PHP in WebSphere sMash Table 13.15 Database Query Functions Function Description dataQueryResults data_query_results Executes a SQL query and returns a ResultSet resource, which can be accessed using the dataResultSet APIs. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: ResultSet of queried records, or NULL if no matching records. dataUpdate data_update Executes a SQL update, such as INSERT, UPDATE, or DELETE. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: int—Number of records updated as part of the SQL alter state- ment. A false is returned if an error occurred. dataUpdateMany data_update_many Executes a batch SQL update. The SQL statement is executed once for each parameter list entry. Arguments: Manager mgr—DataSource manager handle. String sql—SQL statement to process, with optional ‘?’ tokens. Array params—Array of Parameter maps to use in SQL token replacement. Returns: int array—Matching list of number of records updated as part of each SQL alter statement. A false is returned if an error occurred. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 341 Table 13.16 Database Results Functions Function Description dataBlobGetBytes data_blob_get_bytes Returns the contents of the Blob resource as a string. Arguments: Blob handle—The source Blob. int position—Starting byte position to access. Int length—Number of bytes to process. Returns: String containing returned value. dataBlobLength data_blob_length Returns the length of the Blob resource data. Arguments: Blob handle—The source Blob to process. Returns: The length of the Blob as a double. dataBlobSetBytes data_blob_set_bytes Sets the byte contents of the Blob resource. Arguments: Blob handle—The source Blob. int position—Starting byte position to access. String bytes—The bytes to inject into the Blob. int offset—[Optional] Offset within input bytes to process. Default is 0. Int length—[Optional] Number of bytes in input string to write. Default is length of input string. Returns: Number of bytes written as an int, or –1 on error. dataClobGetString data_clob_get_string Returns the contents of the Clob resource as a string. Arguments: Clob handle—The source Clob. Returns: String contents of the Clob. Database Results Functions Functions used to process data returned by query functions are shown in Table 13.16. Download from www.wowebook.com . ptg 332 Chapter 13 PHP in WebSphere sMash Login Extension name: zero.php.LoginServiceExtension This sub-system provides the ability to log into a WebSphere sMash application program- matically process, with optional ‘?’ tokens. Array params—Parameters to use in SQL token replacement. Returns: Map of column names and values. Download from www.wowebook.com ptg WebSphere sMash PHP. call. Array params—Parameters to use in SQL token replacement. Returns: Results from ResultHandler processing. Download from www.wowebook.com ptg 338 Chapter 13 PHP in WebSphere sMash Table