DOC-4996 added trans/pipe page plus fixes

Author: andy-stark-redis

content/develop/clients/hiredis/_index.md

@@ -15,8 +15,9 @@ title: hiredis guide (C)
 weight: 9
 ---
 
-[`hiredis`](https://github.com/redis/hiredis) is the client for the
-[C language](https://en.wikipedia.org/wiki/C_(programming_language)).
+[`hiredis`](https://github.com/redis/hiredis) is the
+[C language](https://en.wikipedia.org/wiki/C_(programming_language))
+client for Redis.
 The sections below explain how to install `hiredis` and connect your application
 to a Redis database.
 
@@ -102,17 +103,20 @@ Reply: OK
 Reply: bar
 ```
 
-The code first uses `redisConnect()` to create the connection to
-use for all subsequent commands.
+The code first uses `redisConnect()` to open the connection for
+all subsequent commands to use. See
+[Connect]({{< relref "/develop/clients/hiredis/connect" >}}) for
+more information about connecting to Redis.
 
 The `redisCommand()` function
 issues commands to the server, each of which returns a
 `redisReply` pointer. Here, the reply is a string, which you can
 access using the `str` field of the reply. The `redisCommand()`
 call allocates memory for the reply, so you should free this
 with `freeReplyObject()` when you have finished using it.
-See [Issue commands]({{< relref "/develop/clients/hiredis/issue-commands" >}}) for more information about 
-handling commands and their replies.
+See [Issue commands]({{< relref "/develop/clients/hiredis/issue-commands" >}})
+and [Handle replies]({{< relref "/develop/clients/hiredis/handle-replies" >}})
+for more information.
 
 Finally, you should close the connection to Redis with a
 call to `redisFree()`. This is not strictly necessary
@@ -122,4 +126,8 @@ to prevent errors.
 
 ## More information
 
+The [`hiredis`](https://github.com/redis/hiredis) Github repository contains
+examples and details that may be useful if you are using `hiredis` to
+implement a higher-level client for another programming language.
+
 See the other pages in this section for more information and examples.

content/develop/clients/hiredis/connect.md

@@ -17,6 +17,11 @@ weight: 1
 
 ## Basic synchronous connection
 
+The example below creates a simple synchronous connection to a local
+Redis server and tests the connection, before closing it with
+`redisFree()`. The `redisConnect()` function takes just a hostname
+and port as its arguments, and returns a context object.
+
 ```c
 #include <stdio.h>
 
@@ -58,4 +63,6 @@ if (reply != NULL) {
 
 // Close the connection.
 redisFree(c);
-```
+```
+
+

content/develop/clients/hiredis/handle-replies.md

@@ -9,9 +9,9 @@ categories:
 - oss
 - kubernetes
 - clients
-description: Handle replies with `hiredis`.
-linkTitle: Handle replies
-title: Handle replies
+description: Handle command replies with `hiredis`.
+linkTitle: Handle command replies
+title: Handle command replies
 weight: 10
 ---
 
@@ -23,7 +23,7 @@ reply formats defined in the
 [RESP2 and RESP3]({{< relref "/develop/reference/protocol-spec#resp-protocol-description" >}})
 protocols, so its content varies greatly between calls.
 
-A simple example is the status response returned by the `SET`
+A simple example is the status response returned by the [`SET`]({{< relref "/commands/set" >}})
 command. The code below shows how to get this from the `redisReply`
 object:
 
@@ -40,7 +40,7 @@ if (reply != NULL) {
 
 A null reply indicates an error, so you should always check for this.
 If an error does occur, then the `redisContext` object will have a
-non-zero error number in its integer `err` field and sometimes a textual
+non-zero error number in its integer `err` field and a textual
 description of the error in its `errstr` field.
 
 For `SET`, a successful call will simply return an "OK" string that you
@@ -58,15 +58,15 @@ the stale pointer later.
 
 The Redis
 [`RESP`]({{< relref "/develop/reference/protocol-spec#resp-protocol-description" >}})
-protocols support several different types of reply format for commands.
+protocols support several different reply formats for commands.
 
 You can find the reply format for a command at the end of its
 reference page in the RESP2/RESP3 Reply section (for example, the
 [`INCRBY`]({{< relref "/commands/incrby" >}}) page shows that the
 command has an integer result). You can also determine the format
 using the `type` field of the reply object. This contains a
-different integer value for each type, and `hiredis.h` defines
-constants for each type (for example `REDIS_REPLY_STRING`).
+different integer value for each type. The `hiredis.h` header file
+defines constants for all of these integer values (for example `REDIS_REPLY_STRING`).
 
 The `redisReply` struct has several fields to contain different
 types of replies, with different fields being set depending on
@@ -306,4 +306,24 @@ if (reply->type == REDIS_REPLY_ARRAY) {
     // >>> Key: address, value: 52 Festive Road
     // >>> Key: hobbies, value: Cosplay
 }
-```
+```
+
+## Handling errors
+
+When a command executes successfully, the `err` field of the context
+object will be set to zero. If a command fails, it will return either
+`NULL` or `REDIS_ERR`, depending on which function and command you used. When
+this happens, `context->err` will contain an error code
+
+-   `REDIS_ERR_IO`: There was an I/O error while creating the connection,
+    or while trying to write or read data. Whenever `context->err` contains
+    `REDIS_ERR_IO`, you can use the features of the standard library file
+    [`errno.h`](https://en.wikipedia.org/wiki/Errno.h) to find out more
+    information about the error.
+-   `REDIS_ERR_EOF`: The server closed the connection which resulted in an empty read.
+-   `REDIS_ERR_PROTOCOL`: There was an error while parsing the
+    [RESP protocol]({{< relref "/develop/reference/protocol-spec" >}}).
+-   `REDIS_ERR_OTHER`: Any other error. Currently, it is only used when the connection
+    hostname can't be resolved.
+
+The context object also has an `errstr` field that contains a descriptive error message.

content/develop/clients/hiredis/issue-commands.md

@@ -9,7 +9,7 @@ categories:
 - oss
 - kubernetes
 - clients
-description: Handle commands and replies with `hiredis`.
+description: Construct commands and send them to the Redis server.
 linkTitle: Issue commands
 title: Issue commands
 weight: 5
@@ -33,7 +33,9 @@ void *redisCommand(redisContext *c, const char *format, ...);
 ```
 
 This function receives a `redisContext` pointer and a pointer
-to a string containing the command. The command text is the
+to a string containing the command (see
+[Connect]({{< relref "/develop/clients/hiredis/connect" >}})
+to learn how to obtain the context pointer). The command text is the
 same as the equivalent [`redis-cli`]({{< relref "/develop/tools/cli" >}})
 command. For example, to issue the command:
 
@@ -47,6 +49,11 @@ you would use the following command with an existing `redisContext* c`:
 redisReply *reply = redisCommand(c, "SET foo bar");
 ```
 
+See the [Command reference]({{< relref "/commands" >}}) for examples
+of CLI commands that you can use with `hiredis`. Most code examples
+in other sections of the docs also have a CLI tab showing
+command sequences that are equivalent to the code.
+
 The command string is interpreted in a similar way to the format
 string for `printf()`, so you can easily interpolate string values from
 your code into the command with the `%s` format specifier:
@@ -65,7 +72,9 @@ in fields of a [hash]({{< relref "/develop/data-types/hashes" >}})) object.
 To do this, use the `%b` format specifier and pass a pointer to the
 data buffer, followed by a `size_t` value indicating its length in bytes.
 As the example below shows, you can freely mix `%s` and `%b` specifiers
-in the same format string.
+in the same format string. Also, you can use the sequence `%%` to
+denote a literal percent sign, but the other `printf()` specifiers,
+such as `%d`, are not supported.
 
 ```c
 char *entryNumber = "1";
@@ -81,7 +90,7 @@ redisReply *reply = redisCommand(c,
 );
 ```
 
-The `redisCommand()` function has a variant `redisCommandArgv()`:
+The `redisCommand()` function has a variant called `redisCommandArgv()`:
 
 ```c
 void *redisCommandArgv(redisContext *c, int argc, const char **argv, const size_t *argvlen);
@@ -106,3 +115,11 @@ const size_t argvlen[] = {3, 8, 5};
 
 redisReply *reply = redisCommandArgv(c, argc, argv, argvlen);
 ```
+
+## Command replies
+
+The information in the `redisReply` object has several formats,
+and the format for a particular reply depends on the command that generated it.
+See
+[Handle replies]({{< relref "/develop/clients/hiredis/handle-replies" >}})
+to learn about the different reply formats and how to use them.

content/develop/clients/hiredis/transpipe.md

@@ -0,0 +1,113 @@
+---
+categories:
+- docs
+- develop
+- stack
+- oss
+- rs
+- rc
+- oss
+- kubernetes
+- clients
+description: Learn how to use Redis pipelines and transactions
+linkTitle: Pipelines/transactions
+title: Pipelines and transactions
+weight: 20
+---
+
+Redis lets you send a sequence of commands to the server together in a batch.
+There are two types of batch that you can use:
+
+-   **Pipelines** avoid network and processing overhead by sending several commands
+    to the server together in a single communication. The server then sends back
+    a single communication with all the responses. See the
+    [Pipelining]({{< relref "/develop/use/pipelining" >}}) page for more
+    information.
+-   **Transactions** guarantee that all the included commands will execute
+    to completion without being interrupted by commands from other clients.
+    See the [Transactions]({{< relref "/develop/interact/transactions" >}})
+    page for more information.
+
+## Execute a pipeline
+
+There is no command to explicitly start a pipeline with `hiredis`,
+but if you issue a command with the `redisAppendCommand()` function,
+it will be added to an output buffer without being sent
+immediately to the server.
+
+There is also an input buffer that receives replies from
+commands. If you call `redisGetReply()` when the input buffer is empty,
+it will first send any commands that are queued in the output buffer and
+then wait for replies to arrive in the input buffer. It will then return
+the first reply only.
+
+If you then make subsequent `redisGetReply()` calls, they will
+find the input buffer is not empty, but still has replies
+queued from previous commands. In this case, `redisGetReply()`
+will just remove and return replies from the input buffer
+until it is empty again.
+
+The example below shows how to use `redisAppendCommand()`
+and `redisGetReply()` together:
+
+```c
+redisAppendCommand(c, "SET fruit:0 Apple");
+redisAppendCommand(c, "SET fruit:1 Banana");
+redisAppendCommand(c, "SET fruit:2 Cherry");
+
+redisAppendCommand(c, "GET fruit:0");
+redisAppendCommand(c, "GET fruit:1");
+redisAppendCommand(c, "GET fruit:2");
+
+
+redisReply *reply;
+
+// Iterate once for each of the six commands in the
+// pipeline.
+for (int i = 0; i < 6; ++i) {
+    redisGetReply(c, (void**) &reply);
+
+    // If an error occurs, the context object will
+    // contain an error code and/or an error string.
+    if (reply->type == REDIS_REPLY_ERROR) {
+        printf("Error: %s", c->errstr);
+    } else {
+        printf("%s\n", reply->str);
+    }
+
+    freeReplyObject(reply);
+}
+// >>> OK
+// >>> OK
+// >>> OK
+// >>> Apple
+// >>> Banana
+// >>> Cherry
+```
+
+`redisAppendCommand()` has the same call signature as `redisCommand()` except that
+it doesn't return a `redisReply`. There is also a `redisAppendCommandArgv()`
+function that is analogous to `redisCommandArgv()` (see
+[Issue commands]({{< relref "/develop/clients/hiredis/issue-commands" >}})
+for more information).
+
+`redisGetReply()` receives the usual
+context pointer and a pointer to a `redisReply` pointer (which you
+must cast to `void**`). After `redisGetReply()` returns,
+the reply pointer will point to the `redisReply` object returned by
+the queued command (see
+[Handle command replies]({{< relref "/develop/clients/hiredis/handle-replies" >}})
+for more information). 
+
+Call `redisGetReply()` once for each command that you added to the pipeline.
+You should check for errors after each call and free each reply object
+when you have finished processing it, as in the example above.
+
+## Transactions
+
+`hiredis` doesn't provide any special API to handle transactions, but
+you can implement them yourself using the [`MULTI`]({{< relref "/commands/multi" >}}),
+[`EXEC`]({{< relref "/commands/exec" >}}), and [`WATCH`]({{< relref "/commands/watch" >}})
+commands as you would from [`redis-cli`]({{< relref "/develop/tools/cli" >}}).
+See [Transactions]({{< relref "/develop/interact/transactions" >}})
+for more information.