Skip to content

Commit a1ad5ee

Browse files
gregor-jgregor-j
committed
add usage documentation
1 parent e14d9bc commit a1ad5ee

File tree

5 files changed

+437
-0
lines changed

5 files changed

+437
-0
lines changed

Diff for: ‎index.md

+7
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,10 @@ The [common classes and exceptions](common) add logic that is not specific to
1818

1919
The module specific implementations contain code that is specific to [the
2020
underlying PHP-module](php-modules).
21+
22+
## Usage documentation
23+
24+
* [Usage overview](usage)
25+
- [Configure a connection](saprfc-config)
26+
- [Establish a connection](saprfc-connection)
27+
- [Invoke a function call](saprfc-function)

Diff for: ‎saprfc-config.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
## Usage: configure a connection
2+
3+
PHP/SAP supports SAP remote system connection types A and B.
4+
5+
* `\phpsap\saprfc\SapRfcConfigA` configures connection parameters for SAP
6+
remote function calls using a specific SAP application server.
7+
* `\phpsap\saprfc\SapRfcConfigB` configures connection parameters for SAP
8+
remote function calls using load balancing.
9+
10+
Each class has a constant defining its type. In case you have a configuration
11+
instance, you can always determine its type.
12+
13+
```php
14+
<?php
15+
use phpsap\saprfc\SapRfcConfigA;
16+
//creates an empty configuration object of type A
17+
$config = new SapRfcConfigA();
18+
//$type will be assigned value 'A'
19+
$type = $config::TYPE;
20+
```
21+
22+
### Common mandatory configuration parameters
23+
24+
* _client_ The destination in RfcOpen.
25+
* _user_ The username to use for authentication.
26+
* _passwd_ The password to use for authentication.
27+
28+
### Type A mandatory configuration parameters
29+
30+
* _ashost_ The host name of a specific SAP application server.
31+
* _sysnr_ The SAP system number.
32+
33+
### Type B mandatory configuration parameters
34+
35+
* _mshost_ The host name of the message server.
36+
37+
### Type A optional configuration parameters
38+
39+
* _gwhost_
40+
* _gwserv_
41+
42+
### Type B optional configuration parameters
43+
44+
* _r3name_ The name of SAP system.
45+
* _group_ The group name of the application servers.
46+
47+
### Common optional configuration parameters
48+
49+
* _trace_ The trace level, defined by the constants in
50+
`\phpsap\interfaces\IConfig`:
51+
- `TRACE_OFF`
52+
- `TRACE_BRIEF`
53+
- `TRACE_VERBOSE`
54+
- `TRACE_FULL`
55+
* _codepage_ Only needed it if you want to connect to a non-Unicode backend
56+
using a non-ISO-Latin-1 user name or password. The RFC library will then use
57+
that codepage for the initial handshake, thus preserving the characters in
58+
username/password.
59+
* _lang_ The logon Language.
60+
* _dest_ The destination in RfcOpenConnection.
61+
* _saprouter_ If the connection needs to be made through a firewall using a
62+
SAPRouter, specify the SAPRouter parameters in the following format:
63+
`/H/hostname/S/portnumber/H/`
64+
65+
### JSON configuration
66+
67+
The configuration classes implement the
68+
[JsonSerializable interface][jsonserializable]. The configuration can
69+
therefore be stored as JSON by using `json_encode` on the configuration
70+
object. In return both configuration classes support importing configuration
71+
from JSON.
72+
73+
```php
74+
<?php
75+
use phpsap\saprfc\SapRfcConfigA;
76+
//configuration previously exported with json_encode()
77+
$configJson = '{
78+
"ashost": "sap.example.com",
79+
"sysnr": "001",
80+
"client": "002",
81+
"user": "username",
82+
"passwd": "password"
83+
}';
84+
//import JSON configuration
85+
$config = new SapRfcConfigA($configJson);
86+
//this would result in the same JSON as in $configJson
87+
$configJson2 = json_encode($config);
88+
```
89+
90+
### Array configuration
91+
92+
The configuration classes support importing configuration as associative array.
93+
In case you have `.ini` files, you can use [parse_ini_file][parse_ini_file] to
94+
import your configuration as associative array.
95+
96+
```php
97+
<?php
98+
use phpsap\saprfc\SapRfcConfigA;
99+
//configuration as associative array
100+
$configArray = [
101+
'ashost' => 'sap.example.com',
102+
'sysnr' => '001',
103+
'client' => '002',
104+
'user' => 'username',
105+
'passwd' => 'password'
106+
];
107+
//import configuration
108+
$config = new SapRfcConfigA($configArray);
109+
```
110+
111+
---
112+
113+
[Go back to usage overview](usage)
114+
| [Continue with establishing a connection](saprfc-connection)
115+
116+
[jsonserializable]: http://php.net/manual/en/class.jsonserializable.php
117+
[parse_ini_file]: http://php.net/manual/de/function.parse-ini-file.php

Diff for: ‎saprfc-connection.md

+171
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
## Usage: establish a connection
2+
3+
A new connection object is created using a previously created configuration.
4+
5+
Upon creation of a connection object, the configuration is read from the
6+
configuration object. In case a mandatory configuration parameter is missing,
7+
an exception will be thrown.
8+
9+
Creating a connection object doesn't mean an actual connection is established.
10+
You can determine the actual connection status using `isConnected()` and you
11+
can use `connect()` to manually establish a connection.
12+
13+
```php
14+
<?php
15+
use phpsap\saprfc\SapRfcConfigA;
16+
use phpsap\saprfc\SapRfcConnection;
17+
18+
$config = new SapRfcConfigA([
19+
'ashost' => 'sap.example.com',
20+
'sysnr' => '001',
21+
'client' => '002',
22+
'user' => 'username',
23+
'passwd' => 'password'
24+
]);
25+
26+
try {
27+
$connection = new SapRfcConnection($config);
28+
} catch (\phpsap\interfaces\exceptions\IIncompleteConfigException $exception) {
29+
printf(
30+
'Your SAP configuration is missing mandatory parameter(s). Message: %s',
31+
$exception->getMessage()
32+
);
33+
die();
34+
}
35+
36+
//returns boolean false
37+
$connection->isConnected();
38+
39+
//establish an actual connection to the SAP system
40+
try {
41+
$connection->connect();
42+
} catch (\phpsap\interfaces\exceptions\IConnectionFailedException $exception) {
43+
printf(
44+
'Establishing a connection failed. Message: %s',
45+
$exception->getMessage()
46+
);
47+
}
48+
49+
//returns boolean true
50+
$connection->isConnected();
51+
52+
//closes the connection
53+
$connection->close();
54+
55+
//returns boolean false
56+
$connection->isConnected();
57+
```
58+
59+
### Ping a connection
60+
61+
You can determine whether a remote function call is possible by pinging a
62+
connection using `ping()`.
63+
64+
Calling `ping()` will automatically call `connect()` and can therefore throw an
65+
`IConnectionFailedException`.
66+
67+
```php
68+
<?php
69+
use phpsap\saprfc\SapRfcConfigA;
70+
use phpsap\saprfc\SapRfcConnection;
71+
72+
$config = new SapRfcConfigA([
73+
'ashost' => 'sap.example.com',
74+
'sysnr' => '001',
75+
'client' => '002',
76+
'user' => 'username',
77+
'passwd' => 'password'
78+
]);
79+
80+
//leave out try+catch for simplification
81+
$connection = new SapRfcConnection($config);
82+
83+
try {
84+
$pingResult = $connection->ping();
85+
} catch (\phpsap\interfaces\exceptions\IConnectionFailedException $exception) {
86+
printf(
87+
'Establishing a connection failed. Message: %s',
88+
$exception->getMessage()
89+
);
90+
}
91+
```
92+
93+
### Prepare a remote function call
94+
95+
In order to call a SAP remote function you need to prepare the function call
96+
using `prepareFunction()`.
97+
98+
Calling `prepareFunction()` will automatically call `connect()` and can
99+
therefore throw an `IConnectionFailedException`.
100+
101+
In case the requested function does not exist, an `IUnknownFunctionException`
102+
is thrown.
103+
104+
```php
105+
<?php
106+
use phpsap\saprfc\SapRfcConfigA;
107+
use phpsap\saprfc\SapRfcConnection;
108+
109+
$config = new SapRfcConfigA([
110+
'ashost' => 'sap.example.com',
111+
'sysnr' => '001',
112+
'client' => '002',
113+
'user' => 'username',
114+
'passwd' => 'password'
115+
]);
116+
117+
//leave out try+catch for simplification
118+
$connection = new SapRfcConnection($config);
119+
120+
try {
121+
$function = $connection->prepareFunction('HELLO_WORLD');
122+
} catch (\phpsap\interfaces\exceptions\IConnectionFailedException $exception) {
123+
printf(
124+
'Establishing a connection failed. Message: %s',
125+
$exception->getMessage()
126+
);
127+
} catch (\phpsap\interfaces\exceptions\IUnknownFunctionException $exception) {
128+
printf(
129+
'The requested remote function does not exist. Message: %s',
130+
$exception->getMessage()
131+
);
132+
}
133+
```
134+
135+
### The connection ID
136+
137+
A connection object contains a connection ID, which is determined from its
138+
configuration. That means, that the same configuration will result in the same
139+
connection ID.
140+
141+
Using this you can compare two connection objects in order to find out, whether
142+
they use the same configuration. However if you call `connect()` on both
143+
objects, two separate actual connections to the SAP system will be
144+
established.
145+
146+
```php
147+
<?php
148+
use phpsap\saprfc\SapRfcConfigA;
149+
use phpsap\saprfc\SapRfcConnection;
150+
151+
$config = new SapRfcConfigA([
152+
'ashost' => 'sap.example.com',
153+
'sysnr' => '001',
154+
'client' => '002',
155+
'user' => 'username',
156+
'passwd' => 'password'
157+
]);
158+
159+
//leave out try+catch for simplification
160+
$connection1 = new SapRfcConnection($config);
161+
$connection2 = new SapRfcConnection($config);
162+
163+
//$same will be boolean true
164+
$same = ($connection1->getId() === $connection2->getId());
165+
```
166+
167+
---
168+
169+
[Go back to usage overview](usage)
170+
| [Go back to configuring a connection](saprfc-config)
171+
| [Continue with invoking a function call](saprfc-connection)

0 commit comments

Comments
 (0)